How to Read Code
seangoedecke.com
Opinion — commentary, not a factual news event.
Reading code isn’t like reading prose. The trick is to jump around first, because diffs and hidden dependencies are where people get lost.
Based on reporting by seangoedecke.com — read the original for the full story.
Summary, retelling and take written by AI under human oversight; images are AI-generated illustrations. How we work · Report an error
Everyone learns books and emails by starting at the top and moving forward. Code doesn’t work that way. It’s built to run on a machine, not to unfold neatly for a human, and the order is often set by things a writer can’t casually rearrange. That alone makes code a different kind of reading problem.
Then there’s the format. Most of the time, engineers aren’t looking at a clean new program at all. They’re looking at a diff, line by line, with changes scattered through something that already exists. Read that like a novel and the plot slips away. Read it as a sequence of tiny edits and you can miss the parts that were left untouched, which may matter just as much.
The deeper issue is size and structure. Codebases can have dependencies that stretch across the whole system, while even famously knotty books still keep most grammatical relationships inside a paragraph. And large codebases can be enormous — the post points out that War and Peace is around 600,000 words, while many large modern codebases have that many lines. That is not a hobby reading challenge. That is a coordination problem.
So the method here is deliberately out of order. First get the shape. Trace an important path, like the happy path for a new feature, and follow which functions call which. Then fan out to other call sites and other uses of the same data. Use search or jump-to-definition tools for small and large diffs respectively. Treat the rest as a black box until the main thread makes sense. Only after that should you read end to end, and even then the goal is mostly to catch the odd thing you missed earlier.
The piece is blunt about AI, too. LLMs can help, but they do not remove the need to read. The author says they still find major problems in AI-generated code, often not as bugs but as mismatches in intent, and gives an example where a small change turned into a three-thousand-line diff because the agent decided to “fix” a harmless race condition. That’s the real warning here: reading code is still a human judgment job, even when a model is doing some of the typing.
My take — AI-written commentary, not fact-checked reporting
This is the part the shiny demo crowd keeps skipping: code review did not get easier just because generation got faster. AI is very good at producing confident nonsense with a nice indentation pattern, which is almost a feature if you enjoy extra work. The boring skill remains the expensive one: reading carefully, and not outsourcing judgment to a machine that doesn’t share your values.
Read more about this at: seangoedecke.com