Whether you’re a new hire or a seasoned pro, somewhere out there, an unfamiliar codebase is waiting to rear its head at the most inopportune time.
It’s an ugly, poorly-documented, and difficult to understand codebase with too many interdependencies…and everyone who wrote the code is gone. It contains a huge amount of knowledge for even the most senior developer, let alone a junior developer, to retain.
This experience sucks. I’ve been there. There’s no single place that shows you how an entire system works. No shared understanding of how all of the code and functionality map to each other. When I was a senior director of product at Docker, a show-stopping bug brought a launch that we’d been working on for months to a screeching halt. Why? Because the problem was in a part of the system that absolutely no one in the company understood, and everyone was terrified that if they changed something, it would cause catastrophic downstream effects.
In this Guide, you will learn:
What code visibility is and why it matters
How to start making your code more visible
Code visibility best practices
Turns out, we’ve been trying to solve the problem of unfamiliar codebases for 50 years. Back in 1979, a book titled “Principles of Software Engineering and Design” explained that 67% of development time was spent on maintenance. This is now called “program comprehension” in more recent papers, but it’s the same old problem. After nearly 50 years, we still haven’t actually solved the code visibility problem, even though it affects every type of developer, not just junior developers.
It's an especially important problem to solve in open source. We need more developers learning from and contributing to open source so that all of our codebases are more maintainable and resilient. Practically every piece of software includes open source components. The ability to quickly onboard new developers to codebases is one of the most important requirements of a thriving open source ecosystem. Maintainers need more time to efficiently onboard new contributors and teach them all of the ins and outs and gotchas of an open source codebase. And contributors, usually being part-time volunteers, need more time and the tools to efficiently understand all of the ins and outs of the open source project.
At CodeSee, we create software that automatically maps out disparate parts of codebases to help you make sense of unfamiliar code. We call it “code visibility.” But as developers, you should still be writing code with readability and maintainability in mind so that others can comprehend your work quickly and easily.
The problem of unfamiliar codebases
Codebases have become far more complex in recent years. Yet developers are still required to make changes and meet stringent quality and security requirements on the same tight deadlines. You’re left alone to read the code line by line to try to understand what’s going on.
You might spend hours or even days just looking for the right place to start. Or maybe you try to find the exact person to ask, and hope and pray they aren’t on vacation or sound asleep halfway across the globe.
Sadly, even when you finally do manage to build that understanding, it’s almost instantly out of date. Teams ship new code all the time. With each release, another unfamiliar codebase exists—each riskier than the last—because we assume our mental model is accurate after all the code reading we’ve done. Instead, our mental model is the equivalent of unpatched software.
What is code visibility?
At its core, code visibility is about mapping your code so that even the freshest of developers can reason about it.
Code visibility is about capturing knowledge of the various aspects of your codebase:
The what: For example, the programming language used, dependencies, or code metrics like lines of code.
The why: For example, why a block of code was written in a particular way, or the business logic knowledge that applies to a section of code.
The where: For example, where a specific piece fits in the broader application or ecosystem of applications.
Code visibility vs. observability
Now, you might be thinking, “This sounds like observability.” I’m good, right? I understand why you might think that, but there are differences.
Observability is the ability to understand and diagnose the state of a system through monitoring, logging, and tracing. It includes the ability to understand how the system behaves under normal and abnormal conditions, and to identify and diagnose problems when they occur. Observability allows engineers to quickly identify and fix issues, and to make informed decisions about how to improve the system's performance and reliability.
Code visibility offers those same benefits, but during the development process, rather than when your code is already in production. Code visibility tools typically help you understand the code while you're writing it, whereas observability is for when you’re running it. The thing is, both types of tools help you solve different problems at different parts of the code life cycle. You need both!
How to write visible code
Here are some guidelines for creating visible code, which will help you create more maintainable codebases.
First, remember that you might write the code just once, but it will be read countless more times. So make sure to write code that’s easy to read, and avoid being clever—no matter how good it feels.
Next, be sure to tell people where to start. Include this guidance in your code comments, your README files, and in your formal documentation.
Document the why, not just the what. Just writing, “We considered these three options, but we picked option 2,” is still not enough. Why?! Why, why, why! If we have to, we can read the code to understand what you did, but the code never tells us why. Share your brilliance with the world, and save future code divers some trouble. When the next person comes along, they don’t just want to know how it works, they want to know why you didn’t build it some other way that seems better to them. If you considered an option and have good reasons for not using that option, write it down. Otherwise, the next person has to figure that all out again.
Add the why to your code comments, too. If you think or ask yourself any of these things, you may want to write a comment:
“I need to remember to be careful about …”
“Which of these approaches is the right way to do this?”
Provide context in your comments, such as:
The reasoning behind a change
The change’s urgency
How dangerous the change might be
Don’t be afraid to add details. Explain your mental model in your comments and documentation, and include intel like how you implemented features and changes, or why you built it this way instead of some other way. Add diagrams and illustrations in your documentation and include their URLs in the comments. That might entail making an actual codebase map. Put links to decision and planning docs in your pull requests, or better yet, put those URLs directly into your code.
We want to hear from you! Join us on GitHub Discussions.
And write tests! Tests are a detailed description of how your code is supposed to work. And they tell you when they get out of date. I hear people ask for documentation that stays up-to-date automatically, but too often they don’t use the auto-updating documentation system they already have: tests! If your team is struggling to write tests, maybe you can invest some time to make it easier to write tests in your codebase.
This may seem like a lot of effort, but it’s worth it. It will not only make for more maintainable code, but reasoning about the whys of your work will result in better code. If you find yourself wanting to skip some of these best practices, imagine someone having to pour over your code line-by-line to suss out your intentions, the same way you’ve likely had to puzzle over legacy codebases at some point in your career. Do that person a solid and make your code visible.
