Code visibility. It’s sort of a loaded term. When we think of “visibility” in the context of software, concepts like “private versus public,” “open source versus closed source,” or “metrics and observability” might come to mind. Fortunately, that’s not what we’re talking about here.
Instead, by referring to code visibility, we’re talking about having your code mapped in such a way that even the freshest of developers can reason about the code. With code visibility, developers should see why code is structured or written in a particular way. With code visibility, new developers can be productive sooner rather than later.
Code visibility is like having Google Maps for your codebase.
In this post, we’ll cover the main reasons why you need code visibility. Then, we’ll look at how CodeSee gives you the code visibility you need.
But First, a Moment of Sadness
Before we dive into the “why” of code visibility, let’s take a moment to commiserate about code visibility (or the general lack thereof). When you first get started on a new team, project, or codebase, you’ll likely take the following classic steps:
- Examine the README or external documentation. Depending on the maturity of the project, this may be helpful to gain some high-level insights. However, if the documentation hasn’t been vigorously kept up to date, reviewing the documentation might even be hurtful.
- Look at the codebase, traversing directories and reviewing the general structure of the code. The time it takes to do this effectively grows linearly with the size of the codebase.
- Browse the project’s open issues and pull requests. As with looking at the code, the time this takes grows linearly with the size and popularity of the codebase.
Depending on the complexity of the codebase, a new developer may need days—or more likely, weeks—to go through the above steps, and this needs to be repeated for every new member of the team. We also have no guarantee that everyone develops the same mental model or has focused on the same things in the code.
The need for code visibility is often forgotten, especially when we’ve been roughly following the same process for years. Code visibility is crucial. Let’s examine why.
#1 - Level Up Your Code Understanding
General code understanding is about rising above some of the deeper technical details, like language syntax and project structure, and developing an understanding of abstract topics that influence the code. For example, in any codebase, there are natural tiers of importance. The critical code paths that provide the core functionality should be the best explained and have the most attention from a visibility perspective.
This higher level understanding is also important because directory structure seldom elucidates program flow or business logic adequately. Directory structure is no substitute for a visual representation. Code visualization gives everyone the same mental model and code understanding, working in much the same way as a drawing from an architect. That drawing can speak volumes about the project, how it works, and what the result should be.
Code visibility also affects code reviews, helping reviewers to move past simply looking at a diff. Seeing the code paths and annotated knowledge in a codebase enriches code reviews and ensures that they’re driven by context instead of tribal knowledge.
#2 - Evolve Beyond the README
Don’t get me wrong—READMEs are useful tools, and they’re often the starting point for documenting code and establishing code visibility. GitHub even gives you the option to populate a README when creating a repository. The problem comes when your documentation and code visibility don’t evolve beyond the initial README.
Maybe you have created external documentation and visuals to clarify nuances about the codebase. While this is a good step in the right direction, this requires developers to look in multiple places to put together a complete mental model.
Code visibility tooling ties the documentation, knowledge, and code together in one place.
#3 - Bring Issues to the Forefront
The “why” of code often comes from a bug or feature request. These days, those requests almost always start in an issue tracking system and are accompanied by a discussion of how to meet the need surfaced by the request. That discussion and the resulting decision are critical when diving into code and wondering why something was written and who wrote it. How does code visibility help here?
First, code visibility allows you to directly link the originating issue to a piece of code or business logic. This way, in a year, when your developer intern decides to refactor that piece of code, they understand the what and the why behind it. Second, code visibility saves developers time by providing an option to see a summary of the what and the why instead of requiring them to read through the originating issue and all of the subsequent discussion.
#4 - Reduce the Time-to-Effective
Without code visibility, there’s no way to ensure that developers new to a codebase are building the same mental model. This cascades into lengthier code reviews due to lack of understanding, more iterations due to introduced bugs, and at its worst, the potential introduction of security issues.
Think of it like a game of telephone. Without code visibility, you have a lot of chances to misunderstand. Code visibility gives you clarity, significantly reducing the possibility of a misunderstanding.
In addition to ensuring that the whole team is on the same page, code visibility allows for an individual’s expertise to scale with their experience. For example, if a module in your application hasn’t been touched in years, new developers probably don’t need in-depth knowledge of it on Day One. However, they may need it on Day 100. With the right code visibility tools, you can decide what’s more important (and what’s less important) during onboarding.
Ultimately, with code visibility, your developers will require less time to start being effective.
Where CodeSee Fits in Code Visibility
We’ve covered four main points for why you need code visibility. Here’s how CodeSee contributes.
Code Understanding with Visualization
Code visualization is a shot in the arm for code understanding, and that’s what CodeSee Maps provide.
CodeSee automatically maps your codebase so that the links between modules are obvious. CodeSee Maps can highlight things like code hot spots and recently added files. Attention is immediately drawn to the most used pieces of the code.
README 2.0: Code Annotations
READMEs are great, but we need more! CodeSee lets you annotate your code to provide the “who,” “what,” and “why” in a way that makes more sense than a README.
Cut Through the Issue Noise
Have you ever had a GitHub issue or Jira ticket with dozens or hundreds of comments? With a sufficiently sized codebase, the amount of reading that a new developer would need to do could make getting up to speed a difficult task. With CodeSee, you can annotate your maps to summarize the discussion and the resulting decision, saving precious time for those getting familiar with the codebase. This makes reading the issue thread optional and highlights the important takeaways.
Onboard Faster
As much as we can, we want to reduce a developer’s time-to-effective metric. We need new developers to start diving in quickly. That way, they can contribute code that either fixes a problem or enables a feature. If the only way they can develop a mental model of your project is to read the entire codebase along with all of the documentation, you’re not going to see effective contributions from them anytime soon.
With CodeSee Tours, developers can have curated walkthroughs of the codebase to make sure they know the important stuff first and start contributing as quickly as possible.
Conclusion
At the end of the day, we’re all trying to do more with less. Code visibility gives you this, equipping your developers with an accurate and shared mental model of your codebase. With your codebase documented and annotated properly and with visuals, developers can cut through the noise and be more effective quicker.
Code visibility is so important that we’ve built a business around creating tools for development teams to get the code visibility they need. Explore our suite of code visibility tools for maps, onboarding, and code reviews.
