In the last two years, I’ve worked on a few projects passed on to me by other teams. Inheriting an existing codebase can be a challenge, given you weren’t there when architectural decisions were made, you are less familiar with the project domain and client needs, and you are just new to the codebase.
In this post, I’ll cover a few of the ways I’ve learned to ramp up quickly when taking over a project.
Step 0: Prep Work
If the technologies are new to you, create a toy project.
Before taking over a project in a framework or language that is new to me, I always spend some time putting together a sample project with the same technology. It’s beneficial to see what starting projects from scratch feels like before you dive into an existing project. This gives you a general idea of what the project may feel like, and it will help provide context for the new codebase.
This approach also makes it easier to spot patterns that are unique to the project. Most projects have some unique features, and identifying them earlier makes for a smoother experience. For example, one of the first projects I took over had a Rails API that used the repository pattern. Even though it’s a common one, I hadn’t used it previously.
Step 1: Initial Onboarding
Read the readme
This should be obvious. The project probably has a README.md file (or something along those lines). Read it. This is the stuff the previous team thought was most important for you to know (at least the last time they updated it). Hopefully, it’s enough to give you an overview and help you figure out how to build the project. If not, that’s a good topic to bring up in the next section.
Meet with the previous team
The quickest way to get ramped up on a project is to spend time with experts in the codebase. Schedule a meeting with the previous team, or at least their technical lead. Here are a few things you’ll want to cover in that meeting:
- An overview of the project domain
- How to get your development environment configured so you can build the project
- How users will use the application
- How the project is architected
- How the project is tested
- How to deploy the project
Write some code with the old team
If the previous team has the time, it’s a good idea to work with them on the first feature or two. I recommend gathering the new team and the previous team’s technical lead around a large monitor and writing code. The feature will probably be implemented at a fraction of the speed it would be by a single person on the old team, but the amount of knowledge sharing here is huge, and that’s the goal at this stage.
Update the readme
It didn’t occur to me to update the readme of an existing project while onboarding until I saw a coworker do it when he was taking over a project I had been on. The new team is in a fantastic spot to see what’s missing. Did you have to install something new to get the build working? Put it in the readme. Did you need to get account access for CI? Put it in the readme. This will save a lot of pain when anyone new comes onto the project.
Step 2: Ramping In
Implement some features on your own
As you start in on the first few features of your own, it’s important to know how similar features have been implemented. Pick a feature like the one you’re working on, and trace it through to see how it works.
If it’s a GET request on an API, how does the request get picked up by its handler? What layers does it go through to get data from the database? How does that get mapped out in the data shape that is sent back? In the app that consumes that request, how does a user’s action get wired up to make the request? How does it then make its way to be shown in the UI?
If you previously wrote a feature with the old team, this is a chance to test how well you absorbed what you learned.
While implementing the feature, you should follow the same process for testing it. What kinds of tests are in place for similar features? During this phase of the project, I typically don’t test first, but I do add testing once the feature is implemented.
Check in with the previous team
When possible, I’ve found it really nice to have regular conversations with the previous team. Maybe you are finding one part of the codebase challenging to work with. There’s probably either a)something you are missing that they can walk you through or b)a chance that they felt the same pain, making this a good candidate for refactoring. Maybe you’re having trouble writing a feature, and they know a library you should be using to make it easier.
Step 3: Take Ownership
Once you understand (most of) the codebase and you’re writing features, you can add to the project. The next thing is to get comfortable updating the codebase you inherited. You’re not just tacking on features anymore; you’re maintaining a project. This means looking at things from a higher level and answering questions like:
- Is it time to update a dependency?
- Are the patterns used still working now that the project has grown?
- Are there problems with the existing code?
It’s time to make sure that the health of the codebase stays in good shape, and that your team is happy working in it. Take the time to treat the code you’ve inherited the same as if you had written it. Make changes when you see fit, throw out what doesn’t work, and appreciate what’s great about it.