home articles newsletter

How to wrap your head around a new codebase

For the last eighteen months, I’ve spent my time trying to understand bits of code I’d never seen before. Eighteen months later, I still don’t know every corner of this reasonably sized codebase (~300_000 lines of code). But what I do know is how to get familiar with new parts of it.

So today, I’ll try and give you some tips about an understated skill: how to wrap your head around a new (part of the) codebase.

What you probably shouldn’t do

Don’t. Be. Stubborn.

That part, I’ve struggled with a lot. Stubbornness impeded the order of magnitude of my output for months.

I would try to understand the code alone and knock my head on my keyboard for hours on end. Man, my ego REALLY got into the way of my learning curve.

I had that same bad habit when learning Ruby. I would get to the point of self-loathing before asking teachers for help.

When I finally got to teach Ruby to new developers, I saw this was a common mistake. So, ask for help early, ask for help fast.

Once I identified that habit and worked on improving it, both my learning curve and my output skyrocketed.

Some things you could do

The end goal for you is to get how things work, faster and more comprehensively, so you can work on improving the codebase.

What you can do on our own

Of course, you won’t approach a whole new codebase the same way you approach a specific part of it. The granularity of what you want to do changes whether you’re starting a new job or tackling a feature.

If after these steps you still feel unsure about where you should start, take a break. This is the tipping point where you’ll fall into stubborn-mode.

Do you feel you’ve started to pull on a thread but still can’t quite wrap your head around it - “I’m almost there.”? Take a break. This is a tipping point too.

Move on to the next stage.

What you can’t do on your own

Note that depending on your situation, some of these tips cannot be copied and pasted. You’ll sometimes need to adapt.

Some additional steps

That’s it!

Wanna add something to the list? Submit your tip on GitHub.


Rémi - @mercier_remi