How to start exploring a new codebase

Have you ever thought about a situation when you are dropped into the middle of a huge codebase and you need to somehow make your way through it? For example:

• you were assigned to a new project
• you switched teams
• you were hired as a contractor or maybe
• you want to start working on a free software project hosted in a public repo.

The question

How should you even start? What to look for? Sometimes the amount of related projects, the vast tooling or huge amount of documentation may seem just overwhelming.

I myself was in such a situation a few months ago. I was asking myself these same questions. Later on, when new teammembers joined, I’ve been asked this question by one of them.

Let me try to answer this question here.

Right tools

First you need to take care about the tools. Like a craftsman, you need a craft workshop.

Well, I’m not talking about new keyboards or new laptops. It’s great if you have one, as it is always better to have a good hardware that to have a poor one (make sure you find some time to learn your IDE/OS shortcuts). By tools I understand basic software you need to load, edit and run the software in question.

The Development Environment

You should start with your editor.

• use and configure your IDE
• preferably use the one that other people in your team uses; this is beneficial if you want to pair-prorgam together
• apply appropriate codestyle tools:
  • static analysis plugins (if your company uses SonarQube, you might want a plugin that connects with the remote Sonar server)
  • depending on your language, use appropriate plugins for linters or checkers
• learn what the IDE offers in terms of
  • investigating dependencies
  • refactoring
  • plugins and integrations
  • vcs support

If your project does not use code versioning, run away. I’m dead serious.

Version Control System

• learn VCS used in your project. Today it is almost always Git, and almost always there is this one “central” repo where you are synchronizing the work with fellow programmers.
• know the “backend” (GitHub? GitLab? Bitbucket?)
• know the integrations (to Jira, to your IDE, to your collaboration app - Slack, Teams etc.)

Deep dive

Documentation

Review documenttion and Readme files. Check if there are any userguides or architectural documentation. Yes, sometimes this is not up-to-date, and this is not a reason to be discouraged: have a look at such documents anyway. At least skim through it to get a basic insight into naming, system architecture, past problems, challenges etc.

Explore the codebase

Search for the entrypoints. Understand that it is not only main() method that matters: your application might start several web servers, listen to multiple ports, integrate to messaging services, serving content from multiple Rest endpoints. Identify the structure of packages: are they structured by technical function, by business requirement or by the whims of developers. This will help you be more effective when adding new code, searching for the code with specific characteristics or be faster when debugging. And - perhaps this is the most valuable aspect of browsing the code - this will be the begining of “mental model refinement”: the understanding you gained by looking at the documentation will be verified and hopefully validated by comparing it with single source of truth which is the codebase.

Review version control history

This lets you see how the code evolved. You can identify recent problems and fixed bugs, you can check the frequency of releases, feature additions and - perhaps most importantly - you will learn who has been making the changes and whom you can contact.

Basic actions

Run tests and analyze test coverage

Understand where are all the tests, what is their struture, of what type those tests are Understand if there are any end to end test, performance tests, integration tests or smoke tests. Try to run unit tests locally. Run existing test suites amd analyze test coverage to understand quality and reliability of the codebase (how safe are you if you try to refactor?)

Analyze code structure and patterns

Look for common design patterns (in case of Java, class names usually give some good clues), architectural styles (e.g. hexagonal or MVC). This will allow to understand future architecture directions, will help recognize what are the areas for improvement.

Analyze dependencies.

Go throug your pom.xml or build.gradle or whatever build system you are using. This is a very valuable source of information: you will immediately understand what API is used, inside what framework the application runs, what libraries are preferred and what patterns or interactions between software components you might expect.

Communicate with team members

Reach out and find out if there is any meetings cadence like those in agile wolrd: standups, retros, plannings, demos or any other like knowledge sharing sessions or one-on-ones with project leads. Try to take part in those as you can meet new people and learn a lot from them. You can also join an existing code review or browse past code reviews to see what is the main code quality focus within the team. Also it is a good idea to ask if code-related agreements are written down and documented somewhere. If they are not, your first contribution in this project could be setting a meeting with an architect or senior developer, interview about such guidelines and write them down. It will become handy when you or other onboarded devs will joint the project later.

Summary

By following these steps you can systematically approach new software project, gain a deeper understanding of the system and become an effective contributor (or just a maintainer) of the project. And remember that this is a process and will not happen overnight. So stay patient.