On Reading Source Code
There’s a difference between knowing how to use a library and knowing how it works. I’ve spent years trying to bridge that gap, reading Frappe internals to understand how document lifecycles work, digging into CPython to understand the GIL, tracing FastAPI source to see how dependency injection is wired.
The pattern is always the same: something surprises me, I read the source, I come away understanding not just the what but the why.
Why Docs Miss the Point
Documentation describes intended behavior. Source code describes actual behavior. For trivial libraries that’s fine, they’re the same. But for frameworks you live inside, the gap between docs and implementation is where the interesting stuff lives.
Frappe’s permission system is a good example. The docs tell you what you can configure. The source tells you the order in which rules are evaluated, the fallback behavior when a role is missing, the subtle difference between read and select permissions. That knowledge changes how you build, not marginally, but fundamentally.
What I Look For
When I read source code I’m looking for a few things:
- The data model. What assumptions are baked in? What’s normalized vs. denormalized?
- The error paths. How does the code fail? Where does it give up vs. retry?
- The seams. Where are the extension points, and what did the authors not anticipate?
- The history.
git blameis underrated. Knowing why a line exists is often more valuable than knowing what it does.
How I Do It
I start at the entry point of whatever surprised me and follow the execution path. I don’t try to understand the whole codebase at once, that’s a trap. I trace one behavior from the outside in until I hit something fundamental.
The goal isn’t to memorize the code. It’s to build a mental model accurate enough that I’m no longer surprised.
This is the first post on this site. More to come.