7 Ways to Get Acquainted With a New Codebase

Diving into a new unfamiliar codebase can be daunting. When I joined FireHydrant, I reflected on my early process and gathered input and insights from the rest of the FireHydrant team to create this quick playbook on best practices that I’m certain will make tackling any new codebase easier.

As engineers, no matter your experience, you’ve had to face an unfamiliar codebase. This can be when you’re starting at a new company or jumping into an open source project. As I onboarded myself at FireHydrant, I was constantly asking myself whether I was doing everything I could to get comfortable with the codebase. In order to pass on some insights, I decided to jot down the techniques that I had been using, and ask my fellow engineers, who have over 50 years of combined engineering experience, the techniques that they use.

Here are the 7 ways that we find useful when familiarizing ourselves with a new codebase.

1. Ask for a High-Level Overview

First things first, obtaining a high-level overview of the codebase is one of the most beneficial ways to get started. Most companies should include this in their onboarding process, but if yours doesn’t, ask one of your more tenured coworkers for the details.

2. Pairing

Within my first 4 weeks of working at FireHydrant, I had the pleasure of pairing with both a backend engineer and a front-end engineer. Through this process, I learned so much about the codebase and had the opportunity to ask why things were built in a certain way. This is a great opportunity to pick someone else’s brain and I suggest you find a way to fully take advantage of the time, such as reviewing the code and preparing potential questions prior to your pairing session.

FireHydrant’s Head of Engineering, and also a co-founder, Dan Condomitti, stressed the importance of not only pairing, but pairing on more complex issues. His advice is that “even if you’re a super experienced developer and know Rails, it’s still good to be able to see someone else work and ask questions about how (or why) something is implemented.”

Notice the mention of asking questions again, which leads us to the next tip…

3. Ask (a lot of) Questions

Asking questions is a key step to understanding the new codebase you are working with. Such questions may include:

• clarifying something in the codebase that is unfamiliar to you or that you’re struggling to understand

• understanding why something was implemented in a certain way

• obtaining insight into why the code you are writing isn’t functioning in the way you expected

These questions may be beneficial because you likely don’t have the institutional knowledge other team members have, such as whether you’ve discovered a new bug. Another thing to note here is that sometimes a company can have undocumented common knowledge that is overlooked. One of our senior engineers, Mark Starkman, wanted to pass along this bit of advice:

“Ask copious amounts of questions. As hard as companies try, there’s always a lot of undocumented institutional knowledge.”

4. Work Through Bugs

Working through bugs is one of the most useful ways to get acquainted with a new codebase. Why? Mark, said it best:

“I like to make sure that I have a project to work on or a specific bug to fix. This way, I have a purpose for what I’m looking for.”

Working through bugs gives you a purpose for exploring the codebase. You’ll have to dig around and look for the files you need to update for the bug you’re fixing. You will likely need to look at corresponding files to understand how the files you are fixing even work! The hands on experience is such a great way to learn about the codebase and will likely bring up some questions for you to ask other engineers, or lead to an eye-opening pairing session.

5. Read the Specs

This piece of advice is courtesy of FireHydrant’s CEO, Robert (Bobby) Ross, and one that I have yet to implement myself but is something I will be doing soon. Specs will make it easier for you to understand why something is being, or was, built, the intended functionality/purpose, and how it should be, or was, built. This is all super useful information and will help you gain insights on the overarching structure of the codebase.

6. Set Aside Extra Time to Explore the Codebase

One little thing that I’ve been doing since I started, is setting aside an hour or two a week to dive into a section of the codebase I have yet to explore. This helps me get more exposure to the codebase that I wouldn’t otherwise gain if I didn’t purposefully set out to do it.

Another great way to explore the codebase is by reviewing old pull requests. Dan mentioned that “looking through old PRs that work on similar (or just interesting) features can be helpful if it shows you all the integration points or something [similar].”

7. Be Patient With Yourself

Being patient with yourself is such an important thing to keep in mind when getting to know a new codebase. Another of our senior engineers, Justin Camerer, says “take it all slow, learning one piece at a time.” Make sure that you are able to retain the information you are learning by taking it slow. In other words, don’t speed through the process because you feel like you are not learning fast enough.

Take your time. Be patient with yourself. Getting to know a codebase takes time and plenty of practice fixing bugs, pairing with other engineers, reading specs, and asking lots and lots of questions.

I’m going to part ways with y’all using this amazing piece of advice from Justin:

“Remind yourself that you’re not going to understand it all right away. Everyone else understands it because they’ve been working on it for months before. Try to give yourself some slack and be ok with not knowing.”