DEV Community

mubert woo
mubert woo

Posted on

How to Read a Codebase You've Never Seen (Without Getting Lost)

Three days. That's how long I once spent "reading" a codebase before writing a single line of code. Two hundred files, top to bottom, careful highlights in my editor.

On day three I understood less than on day one. I'd read everything and retained maybe six files. When my first ticket finally came in, I still had to ask where to start.

That project taught me the mistake I'd been making: I was reading code like a book. Start at page one, finish at the end. Code doesn't work that way: it's not linear, most of it is boring glue, and nothing you read without a question in mind sticks around. What follows is the method I use now. It takes about 90 minutes, it works on any unfamiliar codebase (new job, open-source repo, a side project you inherited), and it leaves you with two things: one traced path through the system, and a notes file you'll still be using a month later.

First, run the thing

Before you read a single line of code, get the app running locally. I know the README makes this sound like a formality. It isn't: the setup process is your first lesson in how the project actually works.

Every env var you have to guess, every docker compose up that dies on a missing seed file, every "works after you run migrations twice" quirk — that's the codebase telling you where the bodies are buried. Write each one down. (Fixing the setup docs afterwards is also a classic, genuinely welcome first contribution.)

If you truly can't get it running, read the CI config instead. .github/workflows/*.yml is the most honest install recipe a repo has, because a robot has to execute it successfully every day.

One more trick, borrowed from Avdi Grimm: once it runs, deliberately break it. Change a string, flip a config value, delete a route, and watch what error comes out. You're not vandalizing; you're building a map of "if I see THIS error, it came from THAT place." Ten minutes of this beats an hour of reading.

Find the edges, not the center

Don't start with the "important" files. You don't know which ones are important yet, and guessing usually means starting with the biggest, most tangled file in the repo.

Start with the edges instead:

  • Entry points: where does execution begin? For a web app, the routes file (routes.rb, urls.py, app.py, src/index.ts). For a CLI, main(). For a library, the public exports.
  • Boundaries: where does the app touch the outside world? Database queries, HTTP clients, message queues, the file system.

Here's a folder listing that used to intimidate me:

src/
├── api/          ← routes live here (edge)
├── services/     ← business logic (middle, skip for now)
├── repositories/ ← SQL lives here (edge)
├── utils/        ← 340 files of glue (ignore, seriously)
└── index.ts      ← entry point (edge)
Enter fullscreen mode Exit fullscreen mode

The middle of a codebase is mostly plumbing connecting edges to edges. You can infer it later. Read the edges first and the middle starts explaining itself.

Trace one request, end to end

This is the core exercise. If I could keep only one step from this whole method, it would be this one.

Pick one concrete action in the app. One button. "User clicks 'Reset password'." Then follow that single request through every layer, all the way down and back up. The Pragmatic Programmer calls this idea a tracer bullet: one thin path fired all the way through the system tells you more than a hundred files read in isolation.

Concretely, with tools you already have:

# find where the route is defined
grep -rn "reset-password" src/

# find who calls the function you just found
# (or use Find Usages in your IDE: same thing, nicer UI)
grep -rn "requestPasswordReset" src/ --exclude-dir=node_modules
Enter fullscreen mode Exit fullscreen mode

Then set a breakpoint (or drop in a console.log with a marker like >>> TRACE) and click the button for real. Watch the path light up: route → controller → service → query → response. Write down each hop as file:line plus one sentence.

A real trace from a project I joined, as I scribbled it:

POST /reset-password  → api/auth.routes.ts:41
  → AuthController.reset() → auth.controller.ts:88
    → UserService.findByEmail() → user.service.ts:120
      → users.repo.ts:54  SELECT * FROM users WHERE email = ?
    → Mailer.send() → goes through a queue?? → TODO ask Sam
Enter fullscreen mode Exit fullscreen mode

That single trace taught me the routing convention, where validation happens, that emails go through a queue (I had no idea), and that I needed to ask Sam about the mailer. Fourteen lines of notes, more understanding than my previous three days of reading.

Read the tests like a table of contents

Tests are the only documentation that runs. And test names are a feature list written by someone who cared.

Before reading a module's implementation, read its test names:

test_checkout_applies_discount_exactly_once
test_checkout_fails_when_cart_is_empty
test_checkout_locks_price_at_submission_time
Enter fullscreen mode Exit fullscreen mode

Three lines, and I already know: discounts have a double-apply bug history, empty carts are a real edge case, and prices get locked at submission, not at payment. That's the kind of context that takes weeks to absorb from Slack messages.

You can even dump every test name as a rough feature list:

pytest --collect-only -q        # Python
go test -list '.*' ./...        # Go
npx jest --listTests            # JavaScript
Enter fullscreen mode Exit fullscreen mode

Skim the list. Areas with heavy coverage mean someone got burned there. Areas with none mean nobody dares touch them. Both are useful signals.

Take notes like you'll forget everything

Because you will. In a month, "I'll remember this" becomes "why is there a UserService AND a UserHelper."

Keep one file, NOTES.md, at the repo root (gitignored if it's a work repo). Not documentation for the team — documentation for future you. Mine look like this:

# NOTES — acme-backend

## Mental model
- Request flow: api/ → controller → service → repo → Postgres
- Auth: JWT, checked in middleware/auth.ts. Sessions NOT used here.
- Background jobs: BullMQ, see workers/. Emails go through here!

## Gotchas
- DO NOT touch billing/ until the Nov migration lands (ask Sam)
- Tests need a local Postgres: docker compose up test-db
- utils/dates.ts has TWO date parsers; use parseDate(), not parseDateLegacy()

## Open questions
- Why does checkout retry 3 times? Where is that configured?
Enter fullscreen mode Exit fullscreen mode

The Open questions section is the underrated one. It turns "I'm confused" into a list you can bring to a teammate once a week, instead of interrupting them twenty times a day.

Know when to stop

You will never finish reading a codebase, and that's fine. The goal is a smaller one: knowing the neighborhood you're about to change in.

My rule: I'm allowed to start a ticket when I can trace its main path from memory and name the two files I'll most likely touch. Everything else, I learn on demand, one ticket at a time.

The notes file from that first project still opens with a line I wrote on day one: "don't touch billing/ until the migration lands." The migration landed in March. The line is still there. Some warnings you keep.

Top comments (0)