How to Onboard Into a New Codebase

Last verified Nov 22, 2021

When starting out at a new company, it's common for a new hire to experience a bit of culture shock. The different offices, people, processes, etc. can all be jarring. However, engineers will often be subjected to an additional type of shock during their onboarding. I call this the code culture shock

Code culture shock is specific to working in a new codebase where things might be completely different from what an engineer is used to — things like folder structures, patterns employed, test setups, libraries used, CI/CD processes, etc. Even small differences like lint rules and formatting configs can come as a shock. 

Add to that differences in personal preferences across team members and it can all be quite jarring. However, there is an upside to this shock. It leads to a unique situation that both new engineers and existing team members should be ready to take full advantage of.


Maximum feedback potential

After the initial shock wears off, there’s a small window of time where the potential for honest, unbiased feedback is at its highest — before the perspective shifts from an engineering outsider to a fellow team member. 

This sweet spot occurs shortly after an engineer has acclimated to the codebase, but before they've accepted what they see as “just how it's done.” It's during this window that they have the chance to harness this potential and offer up unique insights to both the team and the larger organization.

There are a few key ways to take advantage of this feeling as the new engineer:

💪️ Reject the impostor

You made it through the interviews, accepted the offer, and now you're ready to do the job, but there's this nagging feeling that maybe you're in over your head. The codebase and processes are foreign to you. You were an expert at your last job and knew the systems inside and out yet now you're lost and questioning yourself. 

Relax, it's going to be ok! You were hired for your potential to learn and contribute. Nobody expects you to be an expert after just a few weeks. Impostor syndrome is real. Acknowledge it, but then set aside those feelings and dive into your new role. 

☀️ Set biases aside

Bring your knowledge, experience, and fresh outlook and leave any biases behind. You'll notice differences in the codebase from what you are used to — it is all new to you after all — but be careful of equating "different" with "wrong". 

"How I would have done it" is not the same as "how it should be done." That's the beauty of code: there can be multiple solutions to a problem. Recognize that while sometimes your way would have been better, oftentimes it's just different.


🛠️ Break stuff

There's a reason we don't develop in production and there's no better way to learn a new codebase than to get your hands dirty. Change something and see what happens. See some room for improvement? Go for it. 

Chances are your workload is probably still light enough for you to have the time to experiment with new ideas. Don't fret if changes don't pan out. You'll still come away with a deeper understanding of the code you're going to be living in.

📓 Document everything

Catalog anything that seems odd or different and write down the questions that are raised. It's not uncommon to ask yourself why did they do it this way? Don't assume the code you're seeing is perfect as is. You don't yet know the history of why things are the way they are. 

It may be that the bit you're looking at was rushed out and corners cut, intending to be revisited at another time. Patterns and libraries change quickly and code gets out of date before you know it. It's ok, if not expected, that you point these things out. Remember, if the code was perfect, you wouldn’t have been hired to work on it. 


🤝 Sharing is caring

Once you're feeling comfortable, reach out to your team or manager and share your feedback. They realize that you're in the unique position to offer fresh thoughts and ideas and welcome it.

Everyone is working toward the same goal of making the best product for our customers. The way we accomplish this is by listening to and learning from each other.

Want to make sure you always remember the great advice in this post? Don't worry, we put everything in a Guru card!