Notes on reading code you didn't write
A repeatable method for entering an unfamiliar repository and finding the truth.
The first version worked, which is exactly why it was hard to see how wrong it was. Everything looked fine in the demo, and everything looked fine until traffic arrived on a Tuesday afternoon and the graph started doing something I'd never seen before.
Setting the scene
I kept a log of every decision during this project, and reading it back a month later was humbling: the choices that aged well were the boring ones, and the clever ones all came with a footnote I hadn't written yet.
By the end of this post you should be able to reproduce the whole thing yourself in under an hour, including the parts I got wrong the first time — those are marked so you can skip them if you're in a hurry.
- Read the error message twice before changing anything
- A second point, kept short on purpose
The naive approach
I want to be honest about the trade-offs here. The approach I settled on solves the problem I had, not every problem of this shape, and there is a clear point where you should reach for something more heavy-duty.
The first version worked, which is exactly why it was hard to see how wrong it was. Everything looked fine in the demo, and everything looked fine until traffic arrived on a Tuesday afternoon and the graph started doing something I'd never seen before.
Everything above is the short version. The full write-up of how this played out is a story for another day — for now, the takeaway is simple: a repeatable method for entering an unfamiliar repository and finding the truth is a decision you make once and revisit deliberately.