Imagine being a developer on day one of joining a new team. Maybe you’re new to the company, or maybe you’ve transferred from a different project to this one.
Your manager says, “I’m all tied up for the next few hours, so let’s do a one-on-one this afternoon. In the meantime, just pull down the code repo and poke around. Get to know the application.”
The next few hours may be a total waste of your time, leaving you just as clueless as when you started.
Or, if the team has excellent code visibility for the project, then you might end up with a clear, high-level understanding of the important parts of the project, how different segments impact one another, and why certain design decisions were made. Can code visibility really give you all of that?
Yes, it can.
In this post, we’ll cover what code visibility is, compare what development looks like with and without code visibility, and consider how CodeSee enables code visibility.
What Code Visibility Captures
At its core, code visibility is about mapping your code so that even the freshest of developers can reason about the code. Code visibility is made possible through tooling that stitches together knowledge about a codebase. Of course, “knowledge” is a broad term, so let’s clarify.
Code visibility captures knowledge for aspects of your codebase that include:
- 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 broader ecosystem of applications.
The holy grail of code visibility, so to speak, would be a tool that does all of these things in an automated way and can dynamically grow with your codebase. Presently, code visibility is still very much in the growth phase as a category of tooling. This means there’s no single tool yet that can fulfill all of these functions, but there are some tools out there that come close.
Now that we have more clarity on what code visibility is, let’s think about what development looks like without code visibility tooling.
Development Without Code Visibility Tooling
Without code visibility tooling, building and transferring knowledge is usually manual and incomplete. Why? Because code visibility is a tough problem!
The trouble starts with how software developers typically work. We start with visuals in our heads of the problem we’re trying to solve, and then we write the instructions to solve the problem. We’ve developed a habit of skipping the critical step of chronicling the visuals, all in the name of speed and feature delivery. Skipping this step creates gaps in the mental model that developers use to write the instructions to solve a problem. And one developer’s gaps are different from another developer’s gaps. Before you know it, those differing mental models lead to bugs and affect the project’s success.
Let’s step back for a moment and consider why this happens.
In most cases, the majority of the critical knowledge for a codebase or application winds up in a README and code comments. Occasionally, a team’s process may evolve, and they start to include diagrams or other visuals to help improve the mental model of the codebase. However, even if your team reaches that next level, that’s usually where it stops.
Updating the documents and visuals becomes a chore that nobody wants to do. The task of updating documentation is often disjointed from the actual code changes, even though the documentation lives alongside the code. As the codebase grows, documentation falls behind. The codebase becomes an increasingly untouchable black box, leading to fear of change and decreasing velocity.
That’s how we land in the well-known and vicious cycle of outdated documentation, tribal knowledge, and frustration.
Development With Code Visibility Tooling
How do we turn this on its head and ensure team success on this journey of code visibility? The answer is simple: We need a tool to do the job.
The right tool should combine insight, automation, and ease of use. It should automatically open the black box that is your codebase by creating the important visuals needed. These visuals show how pieces of the code relate to one another. When using a code visibility tool, code relationships will be apparent from the get-go.
The right tool should also enable shared understanding that can be maintained through code iterations. This can happen through automated updates of the visuals and insights produced when mapping the code. Automated updates coupled with shared understanding yield an added benefit: As you add more engineers to a team, the onboarding is much faster.
Once you have tooling in place, the cascade of benefits can begin. For starters, you won’t have to rely solely on observability in your production environment to catch issues. Code visibility early in the development process ensures that everyone has the same mental model and understands the codebase. With everybody coding in the same direction, the result, of course, is fewer bugs.
CodeSee fills a gap where the overwhelming majority of codebases are lacking: elasticity of knowledge.
CodeSee speeds up onboarding
Once a codebase has a Codebase Map created in CodeSee, you can add virtually any knowledge, including how to get up to speed with the code. Once you have a Map, you can also create customized onboarding flows through CodeSee Tours. A Tour is like the yellow brick road of your codebase. With a well-defined learning path through the code, new developers can onboard and become more effective faster than ever before.
CodeSee simplifies code reviews
By putting the knowledge about the code together with the code, you can ensure that everyone has the same mental model of the codebase. With that in place, you can level up your review process. When a code writer and a code reviewer have the same mental model, this significantly reduces misunderstandings and development cycles. Code reviews become more effective, resulting in higher quality code and deeper opportunities for learning.
CodeSee increases productivity
Developers need to understand a lot to be effective. CodeSee allows developers to pull most of these things together into a single pane of glass. This not only makes them effective faster but also reduces the overhead for more senior developers when it comes to hiring and onboarding.
Conclusion
Code visibility is a complex and evolving category of tooling that enables you to have previously unachievable levels of insight into your codebase. With tools like CodeSee, development teams can finally establish an automatically generated and shared visual model of their codebase. When a team of developers works from the same mental model, the result is higher quality code, higher speed, and more productivity.
