How to Learn a Codebase?

You’ve joined a new team or been assigned to a new project, and now you’re looking at a codebase written by various developers, some of whom are no longer with the company. There are hundreds of thousands of lines of code, and you understand precisely none of it. Does it sound familiar to you?

This can be a daunting situation, especially if you are a junior software engineer or someone just learning to contribute to open source. But where do you start? How can you quickly understand and start contributing to a large codebase? Whether you’re joining a team or diving into an open-source project, understanding the codebase is essential.

In this newsletter, I've summarised all the strategies that have worked really well for me!

🦊 Set up the Development Environment

The first step in understanding a new codebase is to ensure you can run it on your local machine. Setting up the development environment involves cloning the repository, installing dependencies, configuring environment variables, and running the application locally.

During this setup, you’ll likely encounter issues and errors. Take notes on the exact commands you run. If you find that information is missing or could be better documented, add it for the next person. Improved documentation is always appreciated and is a valuable contribution to your team.

🧶 Get an Overview of the Architecture

Understanding the architecture of a codebase is key to working with it effectively. Start by looking at the project's documentation and any diagrams that show how it’s put together. If the documentation is not available or not clear, ask your team members to give you a code walkthrough. Knowing the overall structure will make it easier to understand specific parts of the code and contribute effectively.

Just like setting up the development environment, you can help the team by documenting the project's architecture. Update existing documentation if it exists, or create it if it doesn't. Having a clear architectural documentation is important for the whole team. Also, you don’t need to understand the whole codebase. While i was contributing to Firefox codebase, knowing the whole codebase was impossible. Since then, I've focused on what I need to know, and it's made me better at my job.

💡 Important Tip: Take note of which parts of the codebase are most used. While some files don’t get touched much once created, whereas files that deal with key functionalities like handling business logic, managing data, and routing usually get changed a lot. These are the core components of the codebase, and checking them first can help you understand how everything works.

🌶️ Write Test Cases

Writing or improving test cases is a great way to contribute and learn when you join a new team. It's a safe approach since you won't break anything; instead, you'll make the codebase stronger. Start by setting up the project, running the existing tests, and exploring the system through these tests. If the codebase has unit tests, find areas that need more tests and start there. Writing tests helps you understand how the application works. Tests show you the logic in action and let you get involved with the codebase without causing issues. By improving test coverage, you force yourself to work within the application’s logic, increasing your familiarity with various parts of the codebase.

🪲 Fix Bugs and Debug Code

Reading code or documentation on its own doesn't always give a clear picture of a codebase, but contributing to the codebase does. It's usually best to start with a small task and gradually tackle bigger ones over time. This approach helps build a better understanding of how everything works together. When you fix bugs, you're not just making the code better, but you're also getting a better understanding on how it all fits together.

It takes time to learn the different components of a codebase, especially ones that are large and complex. What's helped me the most is getting hands-on with different tasks, reading the docs and asking lots of questions. For me, the only way things really stick in my mind is when I'm fixing bugs or adding new features. I also recommend checking out the past month's activity and going through old pull requests - they can be very helpful.

Ending Notes

Joining a new team or project can be intimidating, especially when faced with a large and complex codebase. Remember, it's okay not to understand every detail of the codebase right away. Learning is a continuous process, and as you work with the codebase and collaborate with your team, your understanding will get better with time.

Understanding a new codebase is just the beginning of your journey as a software engineer or open-source contributor. Stay curious, keep exploring, and never stop learning. The more you immerse yourself in different projects and technologies, the more versatile and skilled you'll become.