Skip to content
Velloreth
Programming 5 min read

Code Reading Strategies: How to Understand a Codebase

Reading code is most of the job. Learn how to navigate an unfamiliar repository, trace a request, and build a mental model fast.

By

Why reading matters

Reading code is most of the job. A developer writes a few lines and reads hundreds. The skill is rarely taught, and it is the one that determines how fast you become useful in a new codebase.

The goal is a mental model, not a complete understanding. You need to know where a change belongs and what it will affect.

Start with the map

The README — what the project is and how to run it.

The directory structure — the top-level layout is a design statement.

src/
  api/        the HTTP layer
  services/   the business logic
  models/     the data
  lib/        the shared utilities

The manifest — package.json, go.mod, Cargo.toml. The dependencies say what the project is built on.

The configuration — the environment variables and the config files say what the system depends on.

The CI file — the pipeline says how it is built, tested and deployed.

The recent commits — git log --oneline -20 shows what is being worked on.

The map is rough. The point is to know where to look, not to know everything.

Find the entry point

Every system has an entry point. Find it and follow one request.

A web application: the route definition.

app.get('/users/:id', getUser);

A CLI: the argument parser.

A library: the exported function.

A worker: the job handler.

Follow one request end to end. From the route to the handler to the service to the database and back. One complete path teaches more than reading ten files at random.

Read the tests

The tests are executable documentation.

Why they are better than the prose: they are run, so they are usually up to date. They state the intended behaviour precisely. They tell you what is safe to change.

What to read:

  • The test names, which describe the behaviour
  • The setup, which shows the dependencies
  • The assertions, which state the contract
  • The edge cases, which show what the author worried about

A module with no tests is a module where the behaviour is only in the code, and a change is riskier.

Use the tools

Search — find a string, a function name, an error message.

grep -rn "getUser" src/

Go to definition — the editor jumps to the source. This is the single most useful navigation.

Find references — the editor lists every caller. This is how you know what a change will affect.

The debugger — a breakpoint and a step through is faster than reading for a complex flow.

The call hierarchy — the editor shows the callers and the callees as a tree.

A log line — add one at the entry point and at each layer, and watch the order.

A request id — follow one request across the services.

Build the model

The layers. Most systems have a presentation layer, a business layer and a data layer. Identify them.

The data flow. Where does the data come from, where is it transformed, where is it stored?

The boundaries. Which modules talk to which? A boundary is where a change is contained.

The invariants. What must always be true? A user id is unique, an order has at least one item.

The state. What is mutable, and who owns it?

The failure modes. What happens when the database is down, when the API times out?

Change something small

The fastest way to confirm a model is to test it.

Add a log line and see where it appears.

Change a string and see where it shows up.

Break something deliberately and see which test fails.

Write a test for a behaviour you think you understand. If it passes, the model is right.

The feedback is immediate, and it is worth more than another hour of reading.

Reading a function

The signature — what it takes and returns.

The name — what it claims to do.

The tests — what it is expected to do.

The callers — how it is actually used.

The body — the implementation, read last.

A function with one caller is easy to change. A function with many callers is a contract.

A long function is a candidate for a refactor, and it is also a place where a bug hides.

Reading a diff

A pull request is a good place to learn. The diff shows a change and the discussion shows the reasoning.

Read the description first — what the change is for.

Read the tests — what behaviour is being added.

Read the diff — the implementation.

Read the comments — the disagreement is where the design is.

Common mistakes

Trying to read everything first. A small change teaches more.

Reading a file top to bottom. Follow a path instead.

Ignoring the tests. They are the documentation.

Trusting the comments. A comment can be stale; the code is the truth.

Assuming the structure is intentional. Some of it is history.

Not using the debugger. Reading a complex flow is slower than stepping through it.

Reading alone. A question to a teammate saves an hour.

Not writing anything down. A diagram of the flow is worth the ten minutes.

A quotable summary

Reading code is most of the job, and the goal is a mental model rather than a complete understanding. Start with the map: the README, the directory structure, the manifest and the CI file. Find the entry point and follow one request end to end, read the tests because they are executable documentation, and use the tools: search, go-to-definition, find-references and the debugger. Build a rough model, then change something small to confirm it.

For the debugging side, see debugging-strategies-that-work and asking-good-technical-questions. For the broader context, javascript-debugging-console and git-branching-strategies.

Frequently asked questions

How do I read an unfamiliar codebase?
Start with the README and the directory structure, then find the entry point and trace one request end to end. Read the tests for the module you care about, because they document the intended behaviour. Build a rough map before reading any file in detail, and change something small to confirm your understanding.
Should I read the code or the documentation first?
Read the documentation for the intent and the code for the reality. The documentation says what the system is meant to do, and the code says what it does. When they disagree, the code is the truth and the documentation is a bug.
What is the fastest way to understand a function?
Read its signature, its tests, and its callers. The signature says what it takes and returns, the tests say what it is expected to do, and the callers say how it is actually used. A function with no tests and one caller is easier to change than one with many callers.
How do I trace a request through a system?
Find the route or the handler, then follow the call chain. Add a log line at the entry point and at each layer, or use a debugger with a breakpoint. A request id in the logs lets you follow one request across the services.
Why should I read the tests?
The tests are executable documentation of the intended behaviour, and they are usually more up to date than the prose. They also tell you what is safe to change: a test that fails when you change something is a test that documents a requirement.
How long should it take to understand a codebase?
A rough map takes a day. Comfort with one area takes a week. Fluency across the system takes months. The mistake is to try to read everything before making a change; a small change in one area teaches more than a week of reading.