Navigating large codebases. Tips and Tricks.
When I started to work as a software developer, my first job was as a freelancer and after that, I moved into a position in a small consulting company that worked in the telecommunications sector. During these experiences, the relationship that I had with the codebase was the same, I created the code from scratch and in most cases I was the only developer working on it, meaning that I had to decide the architecture, language, and methodology to use in the development process. This also meant that all the code was on the top of my head and for any problem that occurred I knew exactly where to look and the probable cause for it. This helped me improve my design skills and also my coding skills, but there is an aspect of coding that this type of work wasn’t letting me develop, working in a large code base that was not built by one developer. To develop this skill I had to look for other opportunities and ended up working for a big SaaS company that had a product initially developed in 2015 and went through at least 3 renovations. In this article, I’m going to expose what my process was and how I managed to learn to navigate through this “ancient” code base, an ability that every software developer should have.
The first thing you have to do is to get the code running either on your machine or on a developer environment stably. This is a super important step because you rule out one possibility when the changes that you implement break something, you know is not the environment. When you have the code running in your environment, now it’s time to learn the product, this will help to reproduce bugs on to expand on the current functionality that the product has. This learning will depend on the type of product and the company you are working for, but you can ask if there is some kind of training material that the users go through to learn how to use the product, you can also ask the product team (business analyst, product owner or product manager) to give you a walkthrough of the product, this option is better for when you are working on a specific part of the application. Another option is to ask the QA team, if there is one, for the breakdown of the application, besides the product team, the QA team is the one that has a deep knowledge of how the application should work because they test it regularly.
When these walkthroughs are completed you can start diving into the application if you want, but my recommendation is to take advantage of your new hire status and ask people for help. Pair programming or shadowing someone is a great way to pick up work methods and techniques that different developers have, and this is the only time that you are going to have the opportunity to be able to do practice those, because after your “new hire” period is going to get harder that your time and your teammates time coincide to be able to do pair programming, so take advantage of it.
After you have seen how more seasoned developers approach the code base you are ready to get your feet wet, it is that time for you to pick up your first ticket. In large code bases, there are many tickets to work on, you can look through them and pick an easy one so you can start navigating the code on your own, or you can ask your coworkers which one they think is a good one to start with. After you select the ticket you can start trying to develop your solution for it, if it is a bug try to reproduce it, if it is a feature try to find the section of the code that you are going to work on. Understand the flow that the application has, which endpoints are called and what data they return, how those calls correlate with the front end, which parts of the application are handling what, for example, it uses front-end sorting or backend sorting for the information, same goes for pagination, which parameters have to be sent for it to work, which services in the backend are involved and which calls are made to the database to fetch the data. All of these points will help you understand what the application is doing even though you didn’t write it. To find the flow you can use debugging tools according to the framework that you are using, or if you are using an IDE specifically designed for that framework, they have debuggers and data visualization tools that will help with this process. The objective is to know every step that the application makes to get the data and confirm any assumption using debugging tools to know exactly what path the code is taking.
Sometimes, but not always, the code itself will implement some patterns into it, like the filing methodology that the team uses to organize the code, this can make it so much easier to find the section that you want because it should be in one folder on in one branch of the file tree. But as the codebase gets bigger and more people get involved in it, you can’t trust the filing system or the file naming convention as much, but it is a great point to start looking at.
Another place where you can look for how the code is supposed to work and maybe the section that you need to work on is the tests. Tests are the implicit documentation of the codebase, they tell the story of the whole application and, if they are well-written, can tell you exactly what you need. Never overlook the tests, you never know what you can find lingering there.
Some teams and developers are used to writing documentation, especially on new functionality, but this is more hit or miss than all the other options that I presented before. If your codebase has documentation for sure take a look at it, it may have more than technical specifications that will give you context on the intention behind the code that was written.
The options previously presented will help you narrow down the section that you suspect you have to work on, but to know exactly the place, you have to start using a debugger or visible changes to the code, in the case of the front-end change some text to see if it shows where you need it, this way you can confirm that you are in the right spot and start working from there.
So far I have talked about the technical way to work in a large codebase, but there is still one aspect of working in a large application that you have to consider. When you start working on a ticket you have to understand the expected and have a clear objective in mind. Without these, you will encounter scope creep and it will be a nightmare to work on that ticket because every time you finish something, something else comes up. And that goes for you as a developer as well, because if you have the objective of the ticket on your mind, you are less prone to start “fixing” or improving things that have nothing to do with the ticket. If you come up with something that has to be fixed but is not in the scope of what you are working on, a new ticket has to be created to keep track of it.
So, now that you have the objective clear and have narrowed down the section you have to work on, is time to start to write actual code to address the situation. If you are not sure how to do something, use the existing code as documentation, chances are that something similar has been done somewhere in the code, and you just have to tweak it to your needs. This is probably the most overlooked part of coding that I have seen and it is the most important one, remember the existing code is documentation as well and you have to leverage it. With this said there is something that we have to take into account, every time that you are going to base off something that was already in the codebase, ask if the functionality that it has needs improvements before using it because this is the time to improve in the way things are done and not repeat the mistakes of the past that were cemented in the codebase.
This is all I have to share with you about the transition from codebases created by small teams to navigating a large mature codebase. I hope it was useful and helped you grow as a developer. Thank you for reading to the end, give it a clap if you liked it, and check out my other articles on different development topics.
