You’ve become the new owner of a (legacy) codebase and you want to confidently make changes to the code. Here’s the recipe for getting yourself properly onboarded.
Start by understanding the project's purpose, objectives, and the problem it is meant to solve. If you can find someone who’s worked on the codebase, even better! Ask them to walk you through the code base.
The amount (and quality!) of documentation for a code base can go from nothing to extensive. Study all the documentation you can find, and map it out to help you form your mental model.
While studying the documentation, or finding a lack of documentation, you’ll start to have more and more questions. These questions will guide your learning. Take some time to write down your initial set of questions. Don’t hold back, creating a list of 20-30 questions can be done in 15 minutes.
Once you get into the exploration mode, you’ll have plenty more questions to add to this list. Document your questions and answers in a simple QA format, this will have tons of value for others who will come after you.
Clone the repository. Familiarize yourself with the branching strategy and repository structure, and skim through past pull requests and commits. You’d be amazed how much you can learn from doing just this. You’ll find out if there were lively discussions around the implementation of certain features, and how things evolved over time.
Run the code base locally (it’s a safe space!), and run the tests. Well written tests are good documentation of the functionlity. If you can’t run the code locally, this is your first challenge. Document your adventures for who ever comes after you. Add it to the existing README.md, or create your own.
If the tests are failing, find out what the last time was the tests did pass, and what has happened since then. Fix the tests, and again – document your adventures.
Explore the code base by first looking at the folder structure, discover the patterns that have been used in structuring the code. Identify the key components. Follow the data. Add temporary comments to the code if you need to, and add questions to your list.
Inspect the dependencies on libraries/framerworks, are you familiar with these? Do a quick skim through documentation of the things that are unknown to you. Create some more questions (what does X do?), and add these to your list.
What other (up/downstream) systems does the code base interface with and depend on? How are these contracts defined? And who owns them? There, more questions!
Your list of questions could have gotten scary long by now! To prevent yourself from being overwhelmed by the sheer size or complexity of the codebase, just split your exploratory work up into smaller chunks, like you would when you would build something of a similar size yourself.
It would be a bit unfair to expect yourself to grasp a year of work in a single day, right? Acknowledging the fact that onboarding can take serious time and even needs to be planned can feel like a bad thing, as you’d only like to have a quick peek at the codebase and start being productive on day one right? But it doesn’t work that way. Investing this time up front will make you go fast later on. Go slow to go fast.
As you become more comfortable with the codebase, take ownership of specific areas or features. Contribute to discussions and propose improvements. Make small changes first, and work your way up to the bigger stuff.
If you postpone the work needed to get that thorough understanding, the code base will be less enjoyable to work in. It will simply stay foreign to you. Try and get yourself to the point where you feel as if it is one of your own projects, where you know the inputs, processes, and outputs – you’re the expert.
And the order of all of these steps is not that significant. The important thing to understand is to
get yourself confidence by putting in the work.