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 Velloreth
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.
Related reading
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.