Reading unfamiliar code quickly: a technique, not a talent

First day in an unfamiliar repository, no context, and nobody has time for an introduction. The usual reflex is to start at the top and read: folder by folder, file by file, until the picture comes together. After three days you have seen a lot and understood little.

The mistake is not the pace. It is the assumption that understanding comes from reading. A codebase of three hundred thousand lines does not fit into one head, and it does not need to. What fits is a map.

Code is not read, it is interrogated

The difference is between walking a city street by street and knowing how to ask for directions. Professional reading is a sequence of questions, each of which shrinks the territory.

Not: what does this say. But: where are decisions made, where does the data flow, what does nobody here touch voluntarily. Wanting to understand everything is not a goal. It is the absence of one.

From that follows an order, and the order is the actual content of this technique.

First: boundaries, not contents

Before the first line of code comes the structure. Folders, modules, dependencies between the parts. In an iOS context that means literally this: the package description and the project file get read before the code.

It costs half an hour and produces the map of districts. How many modules are there, what depends on what, are there boundaries at all or is everything one target. That half hour decides whether the next few days happen inside a structure or on a plain.

Second: the points where the app assembles itself

Then the entry points: where the application starts, where dependencies get wired, where navigation is decided. These places are revealing because they show what the architecture claims about itself.

Often the first contradiction is right here. A project that declares clean layers but creates two dozen singletons on the startup path has already given its answer. No feature code needs to be read for that.

Third: the history instead of the code

The most underrated step. Before I go deep on a strange spot, I ask the version history.

Which files change most often: that is the centre of gravity of the codebase, regardless of what the folder structure suggests. Frequent changes mean this is where the product lives.

Who wrote an odd line and in what context: the answer to the why sits in a commit message more often than in the code. And a run of entries reading "fix", "fix again", "really fix" marks a swamp more reliably than any documentation. Those spots are the expensive ones later, and you know them before touching anything.

Fourth: a single vertical cut

Only now the code, and along one single feature, from the tap through to the network layer and back. One honest cut through all the layers teaches more about the project's patterns than reading ten layers horizontally, because the remaining features are almost certainly built the same way.

What becomes visible is the house style: how errors are handled, where state lives, whether there is one convention or three. From the second cut onward you learn almost nothing new, and that is the signal to stop reading.

Tools that belong to reading

The debugger is not a verification device but a reading instrument. It answers questions, though; it does not ask them: a breakpoint only makes sense once you have a hypothesis for it to confirm or refute. That is why it sits here and not at the start. One run with execution paused replaces an hour of tracing by eye, as soon as you know where to pause.

Existing tests read as a statement of intent: they show what mattered enough to the authors to be protected. That is different information from whether the code works.

And the best way to check your own understanding is a test you write yourself against a module you believe you understand. If it does not pass, the assumption was wrong. That feedback does not come any cheaper.

Write it down, or it evaporates

Understanding that is not written down is gone within a week. What I take down is not a summary, though, but a list of hypotheses: networking appears to run entirely through this one place; this module looks dead, check; two conventions seem to collide here.

Hypotheses have the advantage that they can be settled. Each is later confirmed or burns, and what remains is a map that holds. A summary, by contrast, stays right for exactly as long as nobody checks it.

Why this is not a talent

People who find their way into a codebase faster do not read faster. They recognise more. Nine out of ten things are known patterns, and those cost no thought: a coordinator, a homemade dependency resolution through global instances, a networking layer with the usual shape. The attention is left over for the rest.

That is why the ability transfers and is not a gift. The pattern library grows with every project, the order of the questions can be adopted, and the discipline not to read everything is a decision.

For clients something practical follows: someone who says they need a few days to say anything solid about a codebase is not slow, they are honest. Someone promising a diagnosis after an hour is selling a horoscope. What actually gets examined in those days I have described elsewhere: what I look at first in an unfamiliar codebase.

What this order costs

The order feels unproductive at the start. You have invested half a day and read not one feature, while somebody who dives straight into feature code can already explain something. That this lead disappears later is only visible later.

The second price: the map is deliberately incomplete. After this procedure I know how the project is built, and not what most of its files say. Anyone expecting completeness does not get it, and in some situations that is the wrong offer.

Where the technique does not carry

It assumes the project compiles and runs. A codebase that does not build is a different genre: there the first job is to get to a running state at all, and reading starts afterwards.

And it is weaker in an environment you have no pattern library for. The first substantial entry into an unfamiliar paradigm takes longer than the hundredth in a familiar one, because the recognition the technique runs on is missing. That is not a weakness of the method but its precondition.

Read little, ask in the right order

Reading quickly means reading little and asking in the right order. Structure before contents, history before speculation, one vertical cut instead of ten horizontal ones, and everything written down that is still a hypothesis.

What looks like experience in this is mostly restraint: the willingness never to have read most of a codebase and to know how it works anyway.