How to understand an existing codebase

Rishabh garg
2 min readJan 18, 2021


Writing code is much easier than reading and understanding an existing codebase.

It’s an overwhelming process and your brain usually gets heated after looking at it.

Here’s are a few things that I use to help me in some way:

1. Don’t jump here and there

This is the very first and important thing but hard to do. Don’t jump from one file to another, one folder to another. This will not get you anywhere.

The right step will be is to start understanding it right from the entry point of the app. For example, you should start with App.js in the case of react-app, server.js in the case of node app, etc.

2. Don’t read the code line by line

You’re going to have a hard time if you start reading and understanding each and every line at this step.

The first goal of yours should be to get the 10K level overview of code, how things are working, what are different pieces of code, how they’re connected and communicating with each other, what are the dependencies of a particular piece of code and more.

3. Start writing and drawing

What? Why writing? Aren’t we supposed to understand the code? Yes.

The best way to understand the code is by writing. Write whatever you’re understanding over time in your own language, even if the documentation exists. Try to explain the code like you’ve to explain all of the pieces to a complete newcomer.

If there are a lot of pieces that are involved. Create architecture diagrams to explain them. Excalidraw is my favorite tool to create diagrams.

Creating diagrams and writing helps me a lot, they literally make it easy to understand because as you write, you think more clearly, you internalize the details and they set in your mind.

4. Start building

Enough understanding. Now, pick up a new feature/existing bug or whatever and start building. No better way to understand the codebase more.

Make things. Break things. Make them again. The whole cycle is exciting and interesting. When you break things, you get to really understand what’s happening and why it’s happening.

All of my learnings and things that have helped and will help me in near future are going to be documented in this essay. So, this will keep changing as I move forward in my journey.

Originally published at on January 18, 2021.



Rishabh garg

Machine Learning Practitioner and life long learner. Twitter: @rishabh_grg