On reading the source

I never went to university, which means I never had a semester where someone walked me through a system’s internals. Everything I understand about how software works, I learned by opening the file.

That started as a coping mechanism. It became the actual method.

The asymmetry

Documentation tells you what the author intended. Issues tell you what other people hit. The source tells you what happens. When those three disagree — and on any library older than a year, they will — only one of them is authoritative.

The cost of reading source is high and the cost of not reading it is unpredictable, which is why most people avoid it. But unpredictable costs are the ones that eat a deadline.

What it looks like in practice

I do not read the whole library. I find the entry point I am calling, follow it until it hits either a syscall, a network boundary, or something I already understand, and stop. That is usually forty minutes and three files.

The compounding effect is the real payoff. After enough of these, unfamiliar codebases stop being unfamiliar in kind. A Rust HTTP framework and a Go one are making the same four decisions about connection lifetime, and once you have seen those decisions made a few different ways you can predict where the sharp edges are before you find them.

The part I got wrong for years

I used to read source as a last resort, after the documentation failed. Now it is closer to first. Not because documentation is bad, but because the twenty minutes I spend confirming that the library does what I think it does is the cheapest twenty minutes in the project.