How to Memorize a Complex Codebase?

5 tricks to remember important pieces of your massive codebase

Does your tech lead always have answers to code questions? Somehow, they always connect the dots between an esoteric symptom/issue and the codebase.

It almost feels like they have memorized the entire codebase. While it seems like magic, it is not. You can do it, too.

Note: Memorizing the codebase does not mean you remember everything line by line. It is about doing these five things:

🌐 1. Know the APIs

Memorize your team’s API surface/workflows. In fact, you should be very familiar with those and not need to refer to the documentation.

Here is what I do:

1. Make a list of the prioritized scenarios.

2. Use the API / product like my customer.

3. Run those scenarios under a debugger and add log lines to understand which code path is being executed.

4. Tests can shed light on nuanced behaviors, so understand & run them.

5. Fix bugs in different areas(very helpful!).

I have seen some engineers who have been on a team for a while but still do not know key areas. So, when a major issue strikes, they rely on others to resolve it.

📑 2. Document & understand the core “flow”

Next, I understand how the code is organized. While there is no alternative to actually reading the code in depth, there are some tricks:

1. know which source files are important vs. which are not.

2. know the lines to focus on vs. skim through

I start by deep-diving into one workflow in code search and under the debugger. Next, I document the classes/files, starting from the API surface layer and working my way through all the dependencies.

• Key classes to know are API handlers, caching layers, database interactions, etc.

• Classes to skim through are the simple utilities, logging helpers, etc.

Note that memorizing the code is not a one-day job. I learn something new every time I look at it, so I keep live notes.

Here is a sample version of my high-level notes:

🕵️ 3. Read older “issues”

Memorizing code is not just about what is visible in it but also about knowing system constraints, bottlenecks, and the sources of repeated problems. Reading about past issues is a great way to learn about these issues.

Here are key things I look for in the past issues

1. How did the system behave with bad inputs?

2. Overload incidents highlight bottlenecks and how the system deals with it.

3. How did the team handle the past issues, and which issues/areas still need attention?

4. Issues that repeat and why

5. How annoyed do critical customers get when our team has issues

🧵 4. Threading model

I have dealt with many production issues, and quite a few were caused by race conditions.

The key to solving those was memorizing the threading model in my head.

Examples of things I try to learn:

1. Can the request threads be blocked in any circumstances?

2. Do the key states get accessed/updated from different threads? Does it have the right locking mechanism?

3. Do the long-running stuff run on their thread pool? Can they be resource-intensive?

4. Were there past issues due to deadlocks or blocked threads?

5. How does the request thread use the cache, and does another thread invalidate the cache?

I document the different kinds of thread pools and their responsibilities, i.e., states they update, code they run, i/o operations, etc.

🔥 5. The crazy stuff

Every codebase has few code blocks that are extremely complex, even with a giant comment section.

Knowing these can make you:

• Effective when esoteric issues strike. It will reduce debugging time as you can connect the dots faster than others.

• good at identifying gotchas with new design proposals

• A great mentor who can help others navigate the complex codebase

I keep a log of such stuff and add to it whenever I encounter such code blocks.

Parting Note

Memorizing the codebase is an important skill for every engineer, especially tech leads. It does not mean you remember things line by line, but you must know the core scenarios, system constraints, and other code nuances.

Don’t expect to learn everything in a day and retain it forever. It is a continuous process. So, keep live notes and spend quality time learning this regularly.

---

🎤 Shoutout

1. Managing up: 3 things I wish I realized sooner by Jordan Cutler

2. Product Thinking by

   Ryan Peterman

3. Prioritize your Tasks Effectively by

   Hemant Pandey

---

If you enjoyed this article, then hit the ❤️ button. It helps!

If you think someone else will benefit from this, then make sure to 🔁 share this post.