I got a computer science degree. I attended two bootcamps. I've read probably 40 programming books. Not a single one taught me how to read code. They all taught me how to write it. Which is bizarre, because the data says I spend more than half my working hours reading code, not writing it.
Xia and colleagues’ field study, published in IEEE Transactions on Software Engineering in 2018, recorded 78 professional developers working on seven projects for 3,148 hours. It reported roughly 58% of observed time on program comprehension across applications, including documentation and browser use. This was activity monitoring, and comprehension extended beyond reading source code. We spend the majority of our professional lives doing something we were never trained to do.[1]
I spent my first five years as a developer reading code badly. I'd start at the top of a file, read every line, and try to build a mental model as I went. It was slow, exhausting, and I forgot most of what I read by the next day. Then I studied how expert developers read code, and everything changed.
Busjahn and colleagues’ 2015 eye-tracking study compared novice and expert programmers reading short Java programs and natural-language text. It found experts read code less linearly than novices:[2]
Novices in that study read code less linearly than natural-language text. The result does not establish equal attention to every line or a general rule about movement between files.
Experts read the study’s code snippets less linearly than novices. The 80/20 allocation and cross-file reading claims require separate evidence.
The key insight: expert developers don't read code. They interrogate it. They come with questions and search for answers. Novices come with no questions and hope understanding will emerge from reading.
Before reading a single line of implementation code, answer these questions:
What is this file/module supposed to do? Read the file name, class name, and any top-level comments. If there's a README in the directory, read it.
What does it depend on? Read the import statements. Group them: standard library, third-party, internal. The imports tell you the vocabulary this code uses.
What does it export? Scan for exported functions, classes, or constants. These are the public API. This is what the rest of the codebase sees.
How big is it? Glance at the line count. A 50-line file requires a different reading strategy than a 500-line file.
typescript
// Phase 1 in action: reading a new file// 1. File name: OrderService.ts -> handles order operations// 2. Imports:import { prisma } from "../db"; // Database accessimport { EventBus } from "../events"; // Event publishingimport { InventoryService } from "./inventory"; // Inventory checksimport { z } from "zod"; // Input validation// 3. Exports:export class OrderService { ... }export type OrderInput = z.infer<typeof orderSchema>;// 4. Size: 280 lines -> medium, probably 5-8 methods
In 5 minutes, before reading a single line of implementation, you already know: this is an order service that talks to the database, publishes events, checks inventory, and validates input with Zod. That context makes everything else easier to understand.
When you encounter a poorly named variable or function, mentally rename it. Don't actually refactor it (yet). Just translate it in your head. d becomes discountPercentage. proc becomes processPaymentTransaction. This tiny act of translation forces active comprehension instead of passive reading.
Keep a running list of questions as you read. Write them down. Don't try to answer them immediately. Just collect them. After reading a function, go through the list and see which ones you can now answer. The unanswered questions guide your next reading.
My question stack for a typical function:
- Why is there a 500ms delay before the retry?
- What happens if validateInventory throws?
- Why is calculateTotal async? (DB call for tax rates?)
- What's the difference between "cancelled" and "voided"?
When you hit a function call you don't understand, don't immediately jump to it. Write down the call and keep reading the current function. After you finish, decide which calls you actually need to understand and investigate those. This prevents the "rabbit hole" problem where you jump to a function, which calls another function, which calls another, and you've lost all context. The code search article covers locating those implementations.
In typed languages, read the types before the logic. Types are a form of documentation that's verified by the compiler. A function that takes an Order and returns a ShippingLabel exposes part of its contract before you read the implementation. Inspect validation, side effects and failure paths as well.[3]
typescript
// The types tell you almost everythingdeclare function calculateShipping( order: Order, destination: Address, carrier: ShippingCarrier, options: ShippingOptions): Promise<ShippingQuote>;// The signature exposes input and output types.// Read the implementation for validation, side effects and failure paths.
When a file has a corresponding test file, read the tests first. Tests show you how the code is supposed to be used, what inputs it expects, and what outputs it produces. They're executable documentation.[4]
// Test names below illustrate intended behavior; implementations are omitted.describe("OrderService.createOrder", () => { it("creates an order with valid items and sufficient inventory", ...); it("throws InsufficientInventory when stock is too low", ...); it("applies discount codes and reduces the total", ...); it("publishes an order.created event after successful creation", ...); it("rolls back the order if payment processing fails", ...);});// Now you know the happy path, two error cases, and two side effects
Like any skill, code reading improves with deliberate practice. Here's a 30-day plan:
Week 1: Read one unfamiliar file per day. Pick a file from a module you don't work in. Apply Phases 1-3. Timebox to 30 minutes. Write a one-paragraph summary of what the file does.
Week 2: Trace one user action per day. Pick a feature. Trace it from the API endpoint through the business logic to the database query. Draw the call graph on paper. The architecture visualisation guide develops that view across modules.
Week 3: Read one open-source project per day. Pick a small, well-regarded project (under 5,000 lines). Apply the framework. Reading other people's code in different styles stretches your comprehension muscles.
Week 4: Read with a partner. Pair code-reading sessions where you and a colleague read the same code and compare interpretations. You'll be surprised how differently two people interpret the same function.
# My Contrarian Take: Reading Code Is More Important Than Writing It
I was wrong about this for most of my career. I thought the value of a developer was in what they could build. I now believe the value is in what they can understand. The developer who deeply understands the system makes better decisions about what to build, where to build it, and what not to build.
The best senior engineers I've worked with aren't the fastest typists or the most prolific committers. They're the ones who read a 10,000-line module and say, "This entire subsystem can be replaced with 200 lines if we change the data model." That insight comes from reading, not writing.
Read all export statements to identify the public API
Read every function signature (skip implementations)
Identify the entry point and main flow
Read the happy path of the most important function
Read the error handling
Check if tests exist and read the test names
Write a one-paragraph summary
List remaining questions
Teach yourself to read code. It's the highest-leverage skill in software engineering, and you probably haven't spent a single hour practicing it deliberately. Start today.
Frequently asked questions
Should I read an unfamiliar repository from the first file?
Start with the question you need to answer and the system boundaries relevant to it. Find an entry point, trace a normal path and inspect the related types and tests. Follow a dependency when it changes your explanation of that path.
What does research say about time spent understanding code?
Xia and colleagues studied 78 professionals on seven projects using recorded activity across applications. They reported roughly 58% of observed time on program comprehension. That category includes activities beyond reading source, such as consulting documentation.
Do experts always read code non-linearly?
Busjahn and colleagues observed experts reading short Java snippets less linearly than novices. The result supports examining reading strategies, while the study’s tasks and participants limit how far it can be generalised to every repository investigation.
Why read tests when trying to understand a function?
Tests can show example inputs, expected outcomes and failure cases that the implementation does not explain clearly. Check the assertions and which paths they exercise. A test name alone describes an intention and needs an implemented test to supply evidence.
No single person can hold a large codebase in their head. A knowledge graph externalizes understanding into a queryable structure. Here's the 4-week playbook to build one.
Choose code search tools for text, symbols and cross-repository exploration. Use ripgrep, GitHub and Sourcegraph queries to find code and related changes.
Apply developer documentation best practices with ADRs, comments and tested examples. Use the WRITE system to keep changes reviewable and find stale guidance.
Compare monorepo vs polyrepo trade-offs for code discovery, ownership and shared contracts. Use practical search and change tasks to assess your own team.