Reading Code You Did Not Write

Much of professional programming is reading. Most of the code a working engineer touches was written by someone else, often years earlier, and it may come with few comments and tests that no longer pass. Writing new code is the part people practice most, which is why reading is often the weaker skill. A method helps. Most of that method is about choosing where to look first.

Start from an entry point

An entry point is wherever execution begins for the behavior in question: a route handler, a command, an event listener, or a test that exercises the feature. Starting from the top of the first file usually wastes time, since much of that code is configuration that does not answer the question at hand.

Search for something visible from outside the code. An error message, a button label or a field name is often the exact string the program uses, and searching for it leads straight to the place where the behavior is produced. The trade-off is that the search can miss setup code that changes behavior everywhere. Note that code for a later pass, once the main path makes sense.

Most editors can jump from a call to its definition and list every place a function is used. Use both. The definition shows what a function does, while the list of callers shows why it matters, and the callers are often the quicker route to the behavior that puzzles you. When the search turns up nothing, ask someone who has worked in the area. Write down what you have already tried first, so the question you bring is specific and their time is well spent.

Follow the data, not the folder structure

Folder structure reveals how the author organized the work. Data reveals what the program does. Pick one input, such as a single request or one row of a file, and follow it through the code. At each boundary, write down what the value looks like: its shape, its type, which fields it has, and what has been removed or added.

This exposes things that reading file by file hides. A field that appears in the output but is never set on the way in is either computed somewhere along the path or a bug. A function that quietly converts units is easy to skip when reading the file that holds it, and hard to miss when tracing a value.

A boundary where the shape changes is worth a note of its own, since it is often where a bug hides or a design decision is recorded.

Read the tests with caution

Tests describe the behavior the author intended and the edge cases they had in mind. They are often the most reliable documentation in a codebase. They can also be stale, skipped or written to match a bug. Run them before relying on them. A passing test confirms the behavior it checks, not the behavior anyone needs. A failing test marks the place where the author's model and the current code disagree, which is often the most useful clue available.

The history of the repository helps as well. The commit that introduced a strange line often explains why the line exists, and its message may record the bug it was meant to fix. Read that before deciding the line is a mistake.

Draw, annotate and run

A diagram of three or four boxes, with arrows for calls and short labels for data, forces a commitment. Writing "the cache is checked before the database" makes a claim that can be wrong, and the claim can then be tested. Keep the diagram disposable. It holds the current understanding and should be redrawn two or three times.

Reading shows what the code appears to do. Running it shows what it does. Set a breakpoint at the entry point and step through once, watching values change. Or change one input on purpose, such as a boundary value, and observe what moves. Both methods test the model against reality, which reading alone cannot do. Experiment on a local copy with fake data. A debugger session against a shared environment with real records can change state other people depend on.

Keep a separate list of unknowns while reading. Phrase each one as a question the code can answer, such as which function sets this value or what happens when the list is empty. Questions like these turn vague confusion into a short list of checks, and most can be settled in a minute by running the code.

Treat generated code as a special case

Some files are produced by a tool and marked as not to be edited by hand. Reading them for logic is usually a poor use of time. Read the generator and its inputs instead. Edits to a generated file are overwritten the next time the tool runs, so the real change belongs in the source the tool reads.

A trace to practice with

Choose a small feature in a project you did not write, or a public project you have not seen before. Find an entry point through a visible string or a test. Follow one input through the code and record the value's shape at each boundary. Then run the code with a changed input and check whether the trace predicted the result. Write a short summary with the path, the three questions still open, and the one thing verified by running. The exercise is complete when you can explain the path to a colleague in a few minutes without reopening the code.