As a software engineer, encountering a new codebase can be a daunting task. Whether it’s diving into a legacy codebase or joining a new team with existing code, figuring out how to understand a new codebase and make changes can take time and patience.
In this article, we will discuss some strategies and tips that can be used to tackle a new codebase with confidence. We will define key terms such as codebase and legacy code and explore why it’s important to understand these terms. By the end of this article, you’ll understand how to use documentation, code debugging, and reverse-engineering to navigate a new codebase effectively. You’ll also learn tips and tricks for identifying core components, understanding high-level design, and more.
Let’s dive into how to understand a new codebase so that your next project kicks off to a smooth start!
Tips for How to Understand a New Codebase
When approaching a new codebase, there are several tips that a software engineer can take to gain a thorough understanding of the code. Every little bit helps here, so the sooner you can feel more confident in the area you’re working, the sooner you can deliver value!
Tip 1: Read (and Write) the Documentation
Reading the documentation is one of the first strategies an engineer can use to understand a new codebase. But this makes one REALLY big assumption — that there’s documentation to begin with. Often, no such thing exists… But that’s okay because the code itself is documentation too!
Documentation provides an overview of the codebase, its functionality and what its different components are responsible for. It can also describe any standards, practices or patterns that were used throughout the codebase. When reading documentation, it’s important to look for examples of its usage. This can help create a basic understanding of how the codebase is structured and how its pieces work together. Further, if there are any diagrams in the documentation, they can provide an overview of the overall architecture of the codebase.
And what you should be doing is trying to build up your own documentation of the code you’re exploring. Write things down. Make lists of functional areas. Try drawing out the different aspects. When you see tip 3 then you’ll have some ammunition read! Once you’ve confirmed your model of the codebase and system is accurate, you could try to add, update, or create the documentation for the next person!
Tip 2: Run the Code and Observe Its Behavior
Running the code and observing how it behaves is a great way to understand the functionality of the codebase. This strategy can be used to identify the different entry points, understand what each component does, and discover any corner cases that may exist. Heck, you might even expose bugs that may exist in the codebase (look at you, adding value to the team already!).
Debugging and stepping through the code is an effective method for a software engineer to understand how the code behaves step-by-step. Not only will you be learning how different parts of the system function, you’ll also be getting familiar with the organization of code in your IDE. One of the big barriers to new codebases is that we’re not even well oriented with different parts of it. Taking the time to dive right in and execute the code forces you into having some seat time with the codebase.
Tip 3: Ask Questions!
If you’re fortunate enough to be joining a team where there are already experiences developers working in the codebase, leverage their knowledge! Many people hesitate to ask questions because they don’t want to be perceived as “not smart” — but that’s not what asking questions implies!
To help you overcome “feeling dumb” for asking questions, try to do some work upfront. Try to answer your questions, and be prepared to explain what you’ve tried so far when you go to ask for help. This will demonstrate to the other person that you’ve at least put in an effort. When people see that there’s effort put in, they’ll usually be very willing to help you!
Tip 4: Partner Up!
What better way to learn than working with other smart people! Partnering up is certainly more of a time investment by requiring someone to step through code with you at the same time, but the benefits of real-time navigating and question asking are huge.
I highly recommend that YOU are in the driver seat for this. Simple asking questions as someone pokes around code is far less effective than you trying to build up the muscle memory of how to explore the codebase!
Strategies for Navigating a New Codebase
A new codebase can be overwhelming and difficult to navigate, but there are several approaches that can be used to make the process smoother. Three strategic tips that can help navigate a new codebase include starting at the top and working down, focusing on high-level design before looking at details, and finding and understanding core components.
Fundamentally what all of these have in common is that they are scoping down the big complex problem into something smaller. This is something we need to get comfortable with as engineers! When we are trying to figure out how to understand a new codebase, we need to accept that the ENTIRE codebase is too big of a problem to solve. So how can we start looking at smaller, more digestible parts?
Let’s check these out!
Strategy 1: Start with the Top and Work Your Way Down
Starting with the main method is a good approach when first reading through a codebase. By starting from the top, you get the big picture of the code hierarchy and how it works. From there, work your way down, tracing each component and function call. This allows you to build a clear understanding of the code’s structure, which in turn helps you make sense of how it works.
While this might be helpful for very linear applications, it might not work out this smoothly. For example, if you have an ASP.NET core application, this might allow you to understand how the service is started… But then what? We can adapt this approach to repeat the process, top down, for hitting different routes and treating those as “entry points”.
Strategy 2: Focus on High-Level Design Before Looking at Details
Focusing on high-level design before diving into details helps understand the overall design principles of the code. Start by identifying the core concepts in the code and how they interact with each other. Look for overall patterns and structures in the codebase, this can be done by using diagrams or visualizations. From there, you can understand how the code works by working your way down to the details.
This large picture approach offers a better overall understanding of the codebase, and how it fits together. For me, personally, this is one of the most effective ways that I learn new codebases. I really appreciate having a solid whiteboarding session with someone who knows the code better and having them do a general block diagram of the different parts of the system.
Once I can see the blocks all split out into different areas, I have a visual of different spots that might be worth my time to go dive into next. Without the visual, I find it takes me much longer to rationalize the code organization. A caveat worth mentioning – I am a software engineering manager in my day job and my current role does not require me to code. Without the visuals, this is significantly more challenging. But as a software engineer writing code, I find I can accelerate the process by using this strategy to supplement when I’m biting off a small bug fix or enhancement.
Strategy 3: Find and Understand the Core Components
Finding and understanding how they work is crucial to the understanding of the entire codebase. Core components typically define the architecture of the software, and they are responsible for many aspects of the code’s execution. Understanding them will help you identify how the different parts of the codebase interact with the core components.
Some examples of core components to consider include:
By starting with some of the core aspects, you can narrow your focus so that you prioritize what’s most likely most important to understand. Instead of accidentally getting caught up in an obscure area, you can put your energy into understanding the central areas.
Wrapping Up How to Understand a New Codebase
In this article, we discussed how to understand a new codebase before we can make modifications or improvements. I listed strategies and tips that can help you and other software engineers navigate complex codebases and gain a better understanding of the code.
It is important to acknowledge that the process of understanding a new codebase can be challenging, especially when working with legacy code. However, the benefits of truly understanding the code before making changes can save time, money, and effort in the long run. It’s not going to be “easy” and it’s going to take time… But you can get a head start with these tips and strategies!
If you’re interested in more learning opportunities, subscribe to my free weekly newsletter and check out my YouTube channel!
