Reading unfamiliar source code

How to navigate a codebase you didn't write — the everyday reality of real software.

You will spend far more of your career reading code than writing it — most of it written by other people, and increasingly by AI agents. Reading code well is a distinct, learnable skill, and it's the prerequisite for changing anything safely. The goal of a first read is not to understand everything; it's to build a map good enough to find where your change belongs.

Start at the boundary

Don't read top to bottom like a novel. Start where the system meets the outside world:

For an app, the entry point (from the project-shape lesson).
For a request, where the request arrives.
For a feature, the button or command that triggers it.

From that boundary, trace one path — a single flow — all the way through: input comes in here, gets transformed there, output leaves over there. One complete thread teaches you more than skimming ten files.

Top-down vs bottom-up

Two complementary modes:

Top-down: start from the high-level entry and follow calls inward, only going deeper where you need to. Best for "how does this feature work overall?"
Bottom-up: start from a specific function or error and work outward to see who calls it and why. Best for "what touches this thing I need to change?"

Switch between them deliberately. Lost going down? Pop back up. Confused at the top? Drill into one concrete piece.

Let the artifacts guide you

A codebase is full of built-in documentation, if you know to use it:

Tests show how the code is meant to be used, with real inputs and expected outputs — often the clearest spec available.
Types (in typed languages) tell you the shape of data flowing through without running anything.
Tools — go-to-definition, find-references, and search — let you jump along the call graph instead of guessing.
An AI agent is excellent here: "explain what this module does" or "where is X used?" — then verify its answer against the code, as always.

Build the map before you change anything

Resist editing the first line that looks relevant. First understand the flow your change sits in and what else depends on the state it touches (systems thinking, again). A change made with a map is local and safe; a change made blind ripples.

A strong habit: before modifying code, write yourself one or two sentences describing how the relevant flow works. If you can't, you don't understand it well enough to change it yet.

Where to go next

Reading reveals structure; designing it is software architecture — how to draw the lines between components so change stays contained.

Finished reading? Mark it complete to track your progress.