Tips for Navigating Large and Unfamiliar Codebases

This is a post in my Junior Developer Diaries blog series. I’m writing more every week, and you can sign up to hear more and read previous posts on my website.

So you’re just starting out new at a company, and maybe it’s your first software job ever. You’re faced with a new, large, unfamiliar codebase and a bug to fix. The codebase is something of a size you’ve never really seen before. Your course assignment projects were a couple of files at most, but this is something else. Fear not. There are things you can do.

Large codebases are like space. Often explored, but not fully understood by a single person.

Follow the Design Patterns

The first tip I have for you is to remember design patterns. Is this code in the MVC pattern? How about MVVM or MVP? Does the codebase use service objects? Does it follow the conventions of similar projects? If you know the bug is probably in a model class, try looking there first, and see if the data access layer or API interaction is buggy.

Now, hopefully, the code base you’re dealing with has some use of design patterns, and if not, well this tip isn’t for you. Remember, you can always ask where a piece of code may be, or ask if a senior could explain the “method to the madness” with regard to code layout. This short introduction will help you form a good mental model of what the codebase looks like, and give you a sense of what does what and where things are.

Reason and Deduce

The next tip is to reason and deduce about the design patterns. Try to think logically about where a bug may be. Here’s an example of my mind troubleshooting a typical modern web app.

So the frontend is getting an error, okay, let’s check the JSON that it’s being sent. Cool, that’s wrong too. So lets check the thing creating the JSON response. Ah, that data object has the wrong value, maybe it’s a layer down, perhaps the way the the model is wrong, so I’ll check the construction and it seems fine. Okay, I’ll check the database, ah, the value there is wrong. Hmmm. What’s writing the value into the database then? I’ll search for places where the model is constructed or modified….etc

This sort of tracing and diving lets you deduce more about the code. You can rule out whole parts of the code base to narrow your search. Of course, you should never have to check line by line of a 50,000 line project. This sort of thinking doesn’t come from day one, it takes a while to accrue. It’ll take time, but if you realise that this thinking is so important, you can work on it, and you should! Soon, you’ll be like Sherlock Holmes making a deduction.

Read the Tests

In disappointingly rare cases, there may be some tests to go along with the code base. These are typically a great resource for learning what a certain unit of code is meant to do, by reading the tests, you can understand the expected behaviour, and then compare that with what you’re actually seeing. In a pure TDD, you’d write a test for a failing case, but often it’s not that simple, and a bug is shared between interactions of different units. Perhaps an integration test could be added to start the troubleshooting.

Use Breakpoints and Stacktraces

Of course, the above tips might only work if you know a bit about the codebase, so as last effort to find out what’s going on, it’s time to use breakpoints. Breakpoints stop execution of the code on a certain line, and from there, you can see the stacktrace to how the code got there. You can use that information to find out where the execution came from, and you can inspect local variables to see how they change as the execution continues.

Some languages (for reasons) don’t let you debug them in this way, so google the way to do it, if possible, for yours.

Time

I think a lot of juniors, or any new hire, place harsh expectations of themselves for coming up to speed and familiarity with a code base. This sort of thing typically takes not hours, but months of work. Don’t worry, this is built into considerations when you’re hired, and the more junior you are, the longer it is expected to take for you to get up to speed.

So, you have the time, use it. Slow down, work logically and methodically. Experiment, learn, and explore. The more you focus on learning what’s there versus just trying to fix it, the better you’ll be able to work in the long run. Theres no excuse to say you dont know what the code does when it’s literally in front of you. Slow down. Read. Learn.

Ask!

Finally, if after all the above (the best programmers take initiative to try before asking), you’re still stuck… then ask! Your team will be able to help.

And those are my tips! What ones do you have? Hopefully this helps with the daunting task of unfamiliar code. Please try not to stress. Breath, remember these and you’ll be fine!

This is a post in my Junior Developer Diaries blog series. I’m writing more every week, and you can sign up to hear more and read previous posts on my website.