Tips on how to approach legacy code

It is very common, or almost certain, that starting a new job or a new project is literally stepping into an existing code base, which has been maintained by many fellow developers. Not all of them are still around. You have thousands of code lines and files at hand.

This is particularly an intimidating situation if you are a junior software engineer, or a new joiner to the team who wants to make a valuable contribution to the new team, but don’t know where to start?

Here is a collection of tips I've used in various roles and projects. It is a personal approach to engage in a legacy code base but I'd love to hear about anything you'd suggest, so don't hesitate to reach out!

TL;DR

• Understand the purpose
• First date with the code base
• It's always about Tests
• Ask your colleagues
• Write Documentation

Understand the purpose

Not by analysing each function : what it takes, what it returns and which ORM we are using. We are talking here about the general purpose of the product at hand. Is it a marketplace? then a platform to make it easy to sell and buy stuff and so on.

It will be easier for you to understand it if you have the final use case in mind so you can have implicit understanding of each macro component and its relation with other components. This is essential domain knowledge to be able to maintain and add new features to the code at hand.

Many companies fail to provide this during the process of onboarding a new member to a legacy project. Any documentation or a general introduction to the project would be helpful, and it could save you days of swimming inside the code blindly without a mental guide on where to go at the end.

First date with the code base

In my opinion, just exploring inside the code base adds an additional layer of understanding. Focus on structure more than implementation details in the first few weeks. If you are a more senior developer, try and understand the approach/paradigm and design pattern used in the underlying code. This will help you remember where everything is from a higher level perspective.

An IDE will give you the power to explore a code base quickly and understand how everything is related in one application.

Ask your colleagues

Once you get a reasonable overview on the codebase, you will definitely start having more specific questions. It will get easier to discuss the behaviour of a specific component easily with your colleagues. So take the chance to deepen your understanding while everything is fresh by asking questions, no matter how stupid they might seem to you!.

One interesting way of doing it, is to ask your question and ask for more clarifications while submitting your first pull requests. First PRs are a great way to add clarifications and comments on the first devs, and will definitely serve for the next person to onboard on the subject as well your next tasks on the project.

It's always about Tests

Tests are a great way to understand what each piece of code does. If it’s done well, the test should be intuitive to give an idea on what the piece of code at hand is intended to do regarding some input.

One day I had to refactor a piece of code that manipulates a graph of task executions with complex and abstract methods, but the Unit tests came to the rescue with illustrations on the comments making it easier to understand what the code should do in each scenario. Next time you feel like optimizing and abstracting something, don’t forget to ensure it is still readable or at least with detailed unit tests to avoid spending time understanding your reasoning behind writing code in such a way.

If there are no tests! you should probably run for your life … ok come back here, just kidding! You should definitely add the missing TUs for the code base you are updating to ensure that you won’t break the specs, and have more confidence in the changes you are adding.

Write Documentation

Now that you gained more knowledge and you started having a detailed picture about the project in mind, it is your turn to add those missing parts from the documentation and preserve the acquired knowledge for the newcomers.

Writing the documentation and improving it while projects evolve is a big concern for critical projects, that’s a beneficial way to reduce the bus factor beside writing comprehensible and tested code.

Conclusion

These are just a small collection of tips I have for people getting started into a new codebase that I've used in the past. There are obviously so many ways of doing this, and different things work for different people and different contexts inside companies.