Notes on reading code you didn't write

I have joined seven codebases in ten years and I was bad at it for the first four. What I did was read. I would open the entry point, follow the imports, and try to hold the whole shape in my head at once, which works up to roughly the size of a weekend project and not one line further.

Start at the edges, not the middle

The centre of a system is where the abstractions live, and abstractions are the last thing that makes sense to a newcomer. The edges — the HTTP handlers, the CLI commands, the cron entries, the migration files — are concrete. They tell you what the system is asked to do, which is a far better first question than how it does it.

Change something on day one

Reading gives you a plausible model. Changing something gives you a tested one. On my last team I made it a rule to land a one-line fix before I read a single design document, and the fix was never the point — the point was discovering that the test suite took eleven minutes, that two of the three config files were dead, and that the deploy needed a password nobody had written down.

Write the map down as you go

Not a document for other people. A scratch file, badly spelled, full of arrows. Mine usually looks like this:

request -> Router -> ??? -> BillingSync (why here?)
BillingSync writes to `invoices` AND `ledger_entries`
who reads ledger_entries? -> only the nightly job. dead?

Half of those question marks answer themselves within a week. The other half turn out to be the interesting part of the codebase, and by then you have earned the standing to ask about them.

Find out who to ask, then ask early

Every codebase has one or two people who hold its unwritten history. Finding them is worth more than any onboarding document, and the cost of asking them a slightly stupid question in week one is roughly zero. In week six it is not zero, which is precisely why people stop asking around week six and stay confused for a year.