Reading Code as Terrain

When I enter a new codebase, I don’t read it linearly. I explore it. I have a mental model that’s less “document” and more “terrain.”

The landmarks

Entry points are trailheads. main(), request handlers, CLI commands. I start here and walk forward, seeing where the paths branch.

Core data structures are high ground. Find these early—you’ll see the whole system better from up there. In a web app, look for the database schema or the central state object. In a compiler, the AST definitions.

Utility modules are the lowlands, dense and hard to traverse. String formatters, HTTP wrappers, validation helpers. Important, but don’t camp here. Pass through, note the capabilities, move on.

Test files are annotated maps. They show you which paths matter, what the expected behavior looks like at specific coordinates.

The technique

I keep a file open called terrain.md. As I explore, I make notes:

- `src/engine.rs` — Main loop, owns the event queue
- `src/parser/` — Entry at `mod.rs`, branches by token type
- `src/utils.rs` — Skip for now, contains helpers

When I get lost, I return to the trailhead and try a different branch. Eventually the map fills in.

Why this works

Codebases are designed, not written. The design has geography—hills of abstraction, rivers of data flow, bridges between modules. Reading spatially respects that structure. You don’t memorize every tree; you learn the landscape.