Don’t Try to Understand It All

5 links


Updated October 11, 2022

Codebases are complex, plain and simple. A codebase’s complexity can be roughly estimated as proportional to the number of engineers who have contributed to the codebase multiplied by its age. As more developers contribute to a codebase over time, the complexity continues to increase.

It’s almost impossible to understand every line of a codebase, especially if you didn’t write it yourself. In fact, even a solo developer who has written every single line of a codebase will forget the details and context of parts of the system over time. They may come back to a file they wrote months ago and struggle to remember how it works.

Setting the right expectations now will help reduce your frustrations in the future. It’s okay if you don’t understand how every line of code in a program works.

As developers, it’s our job to form a mental model of how a program works, and how the pieces fit together to form a complete system. You have a limited capacity in your brain to hold this mental model, and eventually, you’ll hit a saturation point where you’re not able to hold the entire mental model in your head at once. As you learn new parts of the system, you may forget other parts you haven’t visited in a while. It’s natural and common among all software engineers.

Depending on the size of the codebase, it may even take years to feel like you know your way around it. It certainly doesn’t help that the codebase is constantly changing as new features are added, bugs are fixed, tests are written, algorithms are optimized, and engineers come and go. Part of the system you understood months ago might have been refactored since then and now works completely differently. You’ll always be chasing a moving target, so don’t beat yourself up if you don’t understand every corner of a codebase.

The best thing to do is to accept that you won’t have a deep understanding of every single part of a codebase, and that’s okay. As long as you work hard to form a mental model about the parts you’re responsible for, things will start to make more sense. It won’t happen all at once, but given enough time, the picture will become clearer and clearer. The trick is to be patient and get comfortable with reading unfamiliar code, because you’ll be doing it for your entire career.

If you found this post worthwhile, please share!