Working with older codebases

Almost every software developer knows what it’s like to work with old codebases, where a lot of code can leave you puzzled about the original intentions of the previous developers. Here are some things I found that helped me work around the issues I faced.

First Get the Big Picture

Understand the overall purpose and architecture of the application before looking at specific details. Take some time to understand the key components and the way that they work together. This high-level view will put into context any lower-level components you read later on. Drawing an overall flowchart can also be very useful as a reference, which helps you visualize function call trees or even the application’s architectural structure.

Understand the History

Look for any available documentation, even if it’s outdated. Read the commit messages, which sometimes carry more context than the code itself does. If it uses git, check the logs to see how the codebase has evolved over time. This historical insight often explains why certain decisions were made, and those can be critical when you’re considering making big changes. This is particularly helpful when you’re trying to understand changes in several files that seem to be part of the same feature, since looking at the commit for that feature can help you see all the relevant code changes.

Dive into the Code with Small, Manageable Goals

Now that you have a good grasp of history and architecture for your project, the step will be working with small, manageable pieces of code. Take just one function or module and completely trace through its functionality. In this way, you’ll avoid feeling overwhelmed, and the detailed understanding you build about how particular parts of the system work helps when those components interact in complicated ways. It’s also less overwhelming when the scope of what you have to understand is smaller at a time.

Apply Debugging Tools Wisely

With older codebases, effective debugging techniques come in handy. Debuggers let you keep track of precisely what’s happening in the code while it is executed. That can be extremely worthy in comprehending otherwise dark or badly documented logic. Set aside areas you are working on, set breakpoints in them, and you see what is going on at runtime, along with what the states of the variables are. With this direct interaction with the code at runtime, you will have a deeper understanding of the project compared to if you just read it over and over again. When you’re stuck, don’t hesitate to try out the debugger. It might take some time to set up, but it’ll definitely be worth it.

Refactor with Caution and Respect

As you get familiar with the code, you may feel the urge to start refactoring to improve design or performance. Do it with caution, or if time doesn’t permit, not at all. Be sure that there is enough test coverage before you refactor. If needed, write new tests for critical functionality. Remember, refactoring without tests is not a good idea with old codebases, since you might end up accidentally changing functionality, which will come back to bite you in the future.

Document Your Findings and Improvements

As you explore and edit the code, document what you find and improvements that you make. This keeps the documentation current and thus helps any future developers on your project. It also helps to clarify your own understanding as you write out what the functions and structures of the code are doing. This specially applies to any infrastructure related documents, such as deploying to the test environments or connecting to the databases. Specific actions like this can take everyone who works on the project several hours to figure out by themselves, so if you did figure it out, it can save several hours for everyone involved!

Patience Pays Off

Great skill with legacy systems is patience. For a system developed over many years, it will take time to understand and improve. If methodical and patient, slowly but surely, the mysterious or confusing parts of the code will start making sense. You even start getting used to the peculiarities of the project, and before you know it you’ll start feeling confident with your grasp of the codebase.

That’s all for this one!