Working with unfamiliar codebases is uncomfortable. It is easy to get overwhelmed with everything you don’t know. There are deliberate actions you can take to be an “effective beginner” in unfamiliar codebases.
Familiar codebases are within your comfort zone. Someone asks you to add a feature and you know exactly where to add it and what issues to be cognizant of.
You may bump into an unfamiliar codebase when you change projects or jobs. An unfamiliar codebase may use a different programming language or it may use a different paradigm. You are tasked with making changes in such a codebase and you wonder: Where do I start? Do I have to get acquainted with all idioms and tools? What are the good code patterns here?
Below are a few of things that have worked for me. This isn’t an exhaustive list. I’ve noticed a lot of my behavior in regards to this topic is unconscious. So writing, helps me understand it.
Learn the least to get the job done
I deliberately restrict the amount of things I learn at once when working in unfamiliar codebases. Restricting the things I have to learn prevents me from feeling overwhelmed.
Imagine if you had to change the color of a text on a webpage which is rendered in a web framework you are not familiar with. In that scenario I wouldn’t make any effort to dive into the novel state of the art database the application uses. I would instead focus on understanding where the relevant CSS files and HTML templates are. This approach saves you time. If you are curious you can learn about the database later.
This is how you eat an elephant? One bite at a time.
I eventually stumble upon new things I have to learn. But I restrict learning new things to what is relevant to the task at hand.
Lean on what I already know
The knowledge I already have about web applications is still useful in unfamiliar codebases. For example, many web frameworks have similar components that play similar roles even though they may have different names and implementations (e.g. controllers, HTML templates, ORMs, background jobs).
If I had to change the behavior of the application after a user clicks on a button, I’d try to look for the “controller for that particular action”. I’d try to understand “what stands for the controller in this framework” when reading the docs. The knowledge I already have about web development helps me understand the types of components that are usually involved in certain types of changes.
Take notes
It is easy to get lost without notes.
When I have questions I add them to my notes. I frequently sort them so I can understand which questions are more important at a specific time. I also cross questions as I find answers to them.
Large codebases tend to have a lot of indirection and it is easy to get lost. I frequently write all the hops around a chain of methods. I try to describe what is done on each hop. This is useful because frequently I enhance/fix/remove existing behavior. These notes help me clarify in which places I’ll have to eventually make changes.
When I read documentation or watch videos I also write notes summarizing what I’ve learned and how they help me understand the codebase.
Inspect the application
Inspecting is about running the application in order to understand it.
Open the browser and check on the Inspector which HTTP requests were made: Which URL was queried? what was the response? Grep the codebase and find the matching code that is making those requests. Look at the “routes” and find the controllers that are responding to those requests.
Check the logs and look for evidence of queries to external systems. Add information to the logs.
Run the application in development and invoke the developer console during the execution of the request. Inspect the objects returned or passed around methods.
Ask for help
Everything is easier if you can just ask somebody. Nevertheless, a lot of knowledge work involves tacit knowledge and as consequence expert practitioners tend to have difficulties transferring it.
Using the techniques above helps coming up with specific questions you can ask.
I can send you my posts straight to your e-mail inbox if you sign up for my newsletter.