Everything else is decoration that will drift out of sync.

the four that earn their place#

The constraint that came from outside.

# The vendor's API rejects batches over 500 even though their docs say 1000.
# Confirmed with their support, ticket #48812, March 2026.
BATCH_SIZE = 500

Nothing in the code can tell you this. Without it, someone raises the number back to 1000 in eighteen months, ships it, and spends a day debugging.

The alternative that was tried and failed.

// Tried sync.Map here first. It was slower for this access pattern — writes
// dominate and the keys are hot, which is the case sync.Map is worst at.
// Benchmark: bench/cache_test.go, BenchmarkHotKeys.

This is the highest-value comment there is, because it stops the next person repeating your experiment. It converts a day of their work into a paragraph.

The non-obvious ordering.

// Must run before initAuth(): the session store reads the feature flag cache,
// which is populated here. Reversing these fails silently — the user gets the
// default flag set rather than an error.

"Fails silently" is the part that matters. A comment marking a trap is worth more than one marking a happy path.

The deliberate weirdness.

// Deliberately not using the iterator: this is on the hot path and the
// bounds checks cost ~8% on the profile. See PERF-221.

Without this, a well-meaning reviewer "cleans it up" and quietly regresses performance. Deliberate ugliness that isn't labelled reads as accidental ugliness, and accidental ugliness gets fixed.

the ones that do not#

Restating the line. // increment counter above counter += 1. This is the canonical example and it is still everywhere.

Section headers in a long function. // ---- validation ---- is a request for an extract function refactor wearing a disguise.

Commented-out code. Delete it. Git has it. A block of dead code with no note is a question nobody can answer: is this a work in progress, a rollback, or something someone forgot?

Changelogs in the file header. // 2019-03-04 JS: added retry logic. That is what the commit log is for, and it is accurate there.

Comments that duplicate the type. // returns a list of user IDs above fn user_ids() -> Vec<UserId>. The signature already said it, and the signature cannot go stale.

the decay problem#

Every comment is a claim that is not checked by anything. The code changes; the comment does not; now it is actively misleading, and a misleading comment is worse than no comment because it is trusted.

Three things reduce the decay:

Put it as close to the fact as possible. A comment above the line it describes survives longer than one at the top of the file describing behaviour forty lines down.

Prefer things that are checked. A well-named function, a type, a test with a descriptive name, an assertion — all of these carry the same information and break when they become false. Reach for those first; comment only what none of them can express.

Reference something durable. A ticket, a benchmark file, a commit hash, a support ticket number, a link to the vendor's documentation. Then a reader who doubts the comment can check it rather than guess.

the test#

Before writing a comment, ask: could I encode this in a name, a type, or a test instead?

If yes, do that — it will be checked, and the comment will not.

If no — if the information genuinely lives outside the code, in a vendor's behaviour or a decision someone made or an experiment that failed — write it down. That is exactly the case comments exist for, and those comments will still be earning their keep in a decade.

Here is the order I go in, and what each thing tells you.

1. can I run it? (15 minutes)#

Clone it. Follow the README. Start a timer.

This is the single most informative test and most people skip it in favor of reading code.

• Under 10 minutes to a running application: the team cares about developer experience, and probably about a lot of other things.
• An hour, with several undocumented steps: onboarding costs a week and every new hire pays it.
• You cannot get it running: the only people who can work on this are the ones who already have it working. This is a serious risk and it is invisible from the outside.

Note every step that failed. That list is the health assessment.

2. the test suite (10 minutes)#

Run it. Then look at it.

Does it pass? On a clean checkout, first try. If not, that tells you the team has normalized a red build.

How long? Under two minutes is excellent. Over ten and people have stopped running it locally.

What is the ratio of assertions to setup? Read three test files. If setup dominates, the code is heavily coupled.

Are there tests for the error paths? Almost nobody writes these and their presence is a strong positive signal.

Is there a skip or xfail graveyard? Count them. A pile of disabled tests means the suite has been losing a slow argument with reality.

3. the shape of the repository (5 minutes)#

tokei .            # lines by language
git log --oneline | wc -l
git log --format='%an' | sort | uniq -c | sort -rn | head

Contributor concentration. If one person wrote 80% of it and they left, that is the largest risk in the codebase, larger than anything technical.

Language sprawl. Four languages in a small project usually means four sets of tooling and nobody who understands all of it.

Directory structure. Does it reflect the domain or the framework? models/, views/, controllers/ tells you nothing about what the software does. billing/, inventory/, shipping/ tells you everything.

4. the largest files (5 minutes)#

find . -name '*.py' -not -path '*/.venv/*' | xargs wc -l | sort -rn | head -20

Every codebase has a few enormous files. Open the biggest one.

• Is it generated? Fine, ignore it.
• Is it a god object? A 4,000-line service class is where all the complexity accumulated and where all the bugs live.
• When was it last changed? git log -1 on it. If it is huge and changes weekly, that is the hot spot, and any work you do will touch it.

5. dependencies (5 minutes)#

How many? Compare against similar projects. An unusual number in either direction is worth understanding.

How old? Anything more than two major versions behind is an upgrade project waiting for you.

Anything abandoned? Check the largest ones for last release date. A critical dependency with no release in three years is a fork you have not made yet.

Anything surprising? A cryptography library nobody has heard of. A vendored copy of something. A dependency on a specific fork.

6. the commit history (10 minutes)#

git log --oneline -50

Message quality. "fix", "wip", "asdf" versus real descriptions. This is a direct readout of the engineering culture and it is remarkably predictive.

Commit size. Are they atomic, or is every commit a 3,000-line dump?

Is there review? Merge commits from pull requests, or direct pushes to the main branch?

Cadence. Steady, or bursts separated by silence?

7. the things that are missing (5 minutes)#

Frequently the most informative part.

• No CI configuration. Nothing is checked automatically.
• No linter or formatter config. Every file is a different style and every review argues about it.
• No CONTRIBUTING.md or equivalent on a project with multiple contributors.
• No changelog. Nobody knows what changed between versions.
• No architecture documentation of any kind. The system exists only in people's heads.
• No .env.example. You cannot configure it without asking someone.

8. one real feature, end to end (10 minutes)#

Pick a user-visible feature and trace it from the entry point to the database.

This is the highest-value ten minutes. You learn: how many layers, how much indirection, where the business logic lives, whether the abstractions are consistent, and whether you could add a similar feature without asking anyone.

If you cannot follow it in ten minutes, neither can anyone else, and every change will be expensive.

the summary judgment#

After an hour I can usually say:

• How long until a new engineer is productive. (From step 1 and 8.)
• Whether changes are safe. (From step 2.)
• Where the risk is concentrated. (From steps 3 and 4.)
• What the team values. (From steps 6 and 7.)

None of that requires understanding what the software does. It is all structural, and structure is what determines the cost of working in something.

Here is a taxonomy of comments worth writing, roughly in descending order of value.

the ones worth writing#

"This will break when X." The highest-value comment there is. A specific failure scenario the author did not consider.

"If two requests hit this concurrently, both will pass the existence check and both will insert. We saw this exact bug in the invoicing path last year."

Concrete, falsifiable, and it comes with evidence.

"This contradicts how we do it elsewhere." Consistency has real value and the author frequently does not know the precedent exists.

"orders/ uses the repository pattern for this. Worth matching, or is there a reason to differ here?"

Note the question at the end. Sometimes there is a reason and you have just learned something.

"I don't understand this." Underrated. If a reviewer with context cannot follow it, a stranger in two years will not either.

This is not an admission of inadequacy. It is a measurement of the code's clarity, and it is a measurement only a reader can take.

"What happens if this fails?" The most consistently productive question in code review. Error paths are the least-considered part of most changes and the most-exercised part in production.

"Is this the right layer?" Business logic in a controller, presentation logic in a model, a database call in a template. Structural, cheap to fix now, expensive later.

"This is good and here is why." Genuinely valuable and almost never written. Naming what worked teaches the pattern and it makes the critical comments land better, because they arrive from someone who is paying attention rather than someone who is looking for problems.

the ones not worth writing#

Anything a formatter or linter handles. If you are commenting on spacing, quotes, or import order, fix your tooling instead. A human enforcing mechanical rules is a broken process.

Style preferences without a reason. "I would have used a map here" is not a review comment, it is a preference. If there is a reason — clarity, performance, consistency with a convention — say the reason. If there is not, do not send it.

Speculative generality. "What if we later need to support multiple currencies?" Usually they will not, and building for it costs now. If you genuinely believe it, say what makes you believe it.

A redesign in a review comment. If the approach is fundamentally wrong, that is a conversation, not a comment thread. Comments are for improving an approach; a different approach needs a discussion, and doing it in review comments after the work is done is the most expensive possible time.

That failure is on the process, not the reviewer: the design should have been discussed before implementation.

how to phrase things#

Distinguish blocking from non-blocking. A convention that removes an enormous amount of ambiguity:

blocking: this deletes rows without the tenant filter
suggestion: this could use the existing helper in utils/dates
question: is the retry here intentional given the caller already retries?
nit: typo in the comment
praise: nice — this handles the empty case correctly, which the old one did not

The author knows exactly what to act on. The reviewer can leave a thought without implying it must be addressed. Both people save time.

Ask rather than assert when you are unsure. "Why does this need a lock?" is better than "this does not need a lock" when you are not certain, and it is better even when you are, because the answer might teach you something about the system.

Explain the why, not just the what. "Use a set here" is an instruction. "Use a set here — this is O(n²) on a list that can have thousands of entries" is teaching, and the author will apply it next time without being told.

Comment on the code, not the person. "This is confusing" rather than "you wrote this confusingly." Small difference, and it consistently changes how the comment is received.

the process problems that comments cannot fix#

The diff is too large. Past a few hundred lines, review quality collapses. The comment "this PR is too large, can you split it" is the most valuable one available and it is socially costly to write, which is why nobody does.

Make it a policy so it is not a personal judgment.

Review is too late. If a fundamental problem is found in review, the process failed earlier. That belongs in design.

Only one person reviews. Different reviewers see different things. For anything significant, two, with different backgrounds.

Comments arrive over three days. The author has moved on and has to reload the entire context. Batch your review into one pass, and do it within a day.

the goal#

The purpose of code review is not to find bugs — tests find bugs more reliably and more cheaply.

It is to spread understanding, maintain coherence, and catch the class of problem that automation cannot see: wrong abstraction, wrong layer, missing case, code that will confuse the next reader.

Comments that serve those are worth writing. Everything else is noise with a notification attached.

It is not taste. A name is the compression of everything the reader needs to know about a thing, and a bad one costs every future reader time. There are rules, they are learnable, and most codebases violate them consistently.

the rules#

1. Length should be proportional to scope.

A loop index used on the next line can be i. A module-level constant read by forty files needs a full sentence of a name.

for i, x in enumerate(items):     # fine, two lines of scope
    ...

MAX_UPLOAD_SIZE_BYTES = 10 * 1024 * 1024   # not MAX_SIZE

The inverse error is as common: for currentItemIndex in ... in a three-line loop is noise.

2. Name what it is, not what it does.

getUserData and fetchUserData and loadUserData all mean the same thing, and the differences imply distinctions you probably do not intend. Pick a convention — get for cheap and local, fetch for network, load for disk — and hold it.

3. Booleans read as assertions.

isValid, hasPermission, canRetry, shouldRefresh. Never a negative: isNotReady produces if not isNotReady, which no human parses correctly on the first read.

4. No abbreviations except universal ones.

id, url, http, db, max, min are fine. usr, cfg, mgr, svc, impl are not. You saved four characters and cost every reader a translation step, forever.

The test: would a competent engineer who has never seen this codebase know what it means? If they would have to check, spell it out.

5. Units in the name.

timeout is a bug waiting to happen. timeoutMs is not. Same for sizeBytes, distanceMeters, priceCents. Every mixed-unit bug I have ever debugged was preceded by a name that did not say the unit.

This is the highest-value rule on this list and it is the most ignored.

6. Avoid meaningless suffixes.

UserManager, DataProcessor, RequestHandler, ThingService. What does a manager do? Nobody knows, which is why the class has grown to nine hundred lines — there is no name-based pressure to keep it focused.

If you cannot name a class without Manager or Helper or Util, it is probably doing several unrelated things and the naming problem is telling you so.

7. Symmetry.

open/close, not open/dispose. start/stop, not start/end. add/remove, not add/delete. A reader who learns half your vocabulary should be able to guess the other half.

8. The name should not lie.

The worst possible name is one that was accurate and is not anymore. validateEmail that also normalizes and saves. getUser that creates the user if absent. These are worse than no name, because the reader trusts them and does not check.

When a function's behavior changes, changing its name is part of the work.

the tell#

Here is the diagnostic that turns naming from taste into information:

If you cannot name it clearly, the thing is probably wrong.

• A function you cannot name without "and" is doing two things.
• A variable you cannot name specifically holds something too vague to be useful.
• A class you can only name Manager has no coherent responsibility.
• A boolean parameter you cannot name is a sign the function should be two functions.

The naming difficulty is a signal about the design, and it arrives at the exact moment when the design is cheapest to change.

the domain language rule#

Use the words your users and your business use, exactly, and use them consistently.

If the business says "subscription," do not call it plan in one module and membership in another. Every translation between the domain language and the code is a place where a misunderstanding hides, and there will be several.

The corollary: if the business uses one word for two things, or two words for one thing, you have found a domain modeling problem that predates your code. That is worth surfacing.

on renaming#

Modern tooling makes renaming safe and cheap in a typed language. Do it. A name that is 20% better, applied across a module, is a real and permanent improvement to every future reading.

The objection is git blame noise, which is a real cost and a small one. git log --follow and blame-ignore files handle most of it.

the one-line version#

Say what it is, include the unit, do not abbreviate, do not lie, and if you cannot name it, fix the thing rather than the name.

Then you get a job and spend, conservatively, eighty percent of your time reading: reading the existing system before you change it, reading a pull request, reading a library's source because the docs are wrong, reading a stack trace, reading a diff a machine produced.

The skill you were never taught is the one you use most. And it is a skill — it is learnable, it has technique, and people are dramatically better or worse at it in ways that have little to do with how well they write.

what good readers actually do#

I have watched a lot of people read unfamiliar code. The good ones have a method.

They find the entry points first. Not the top of the file. The place where control enters the system: main, the route handlers, the message consumers, the event listeners. Everything else is reachable from there and unreachable code is noise.

They read for shape before detail. A first pass that answers: how many layers? Where is the state? What talks to what? They will read a hundred files shallowly before reading one deeply, and they resist the urge to understand any single function completely on the first pass.

They follow the data, not the calls. Where does this value come from, where does it go, who mutates it. Call graphs tell you the structure; data flow tells you the behavior, and bugs live in behavior.

They run it. Reading static text is a bad way to understand a dynamic system. Set a breakpoint, add a print, run the test with a debugger attached. Five minutes of watching it execute beats an hour of reading.

They read the tests first, when the tests are good. Tests are the spec written in a language the machine checks. A well-tested module's test file is the best available documentation of what it is supposed to do.

They read the history. git log -S for the function name. When was this added, what was the commit message, what else changed with it. The rationale for a weird piece of code is frequently in a commit from 2019, and nobody looks.

They accept partial understanding. The bad habit is trying to understand everything before touching anything. You cannot. Understand enough to make the change safely, make it, and let the tests and the review catch what you missed.

the techniques worth practicing deliberately#

Read a library you depend on. Pick something in your stack, one you use daily and have never opened. Read its source for an hour. You will learn more about your language's idioms than from any tutorial, and you will find at least one thing that changes how you use it.

Explain it to someone. The fastest way to discover you did not understand something is to try to say it out loud. This is why rubber-duck debugging works and it works just as well for comprehension as for debugging.

Reconstruct the design decision. For any piece of code that looks strange, ask: what problem would make this the right answer? Usually there was one. Code that looks stupid is either a workaround for something you cannot see, or a fossil of a requirement that no longer exists. Both are worth knowing.

Diff two versions of something. Reading the evolution of a file teaches you what the author learned. It is a much richer signal than the current state.

why this matters more now#

Because reading is now a much larger fraction of the job.

If a machine writes a substantial share of the code that lands in your repository, then your value-add is on the reading side of the transaction. The person who can read a 400-line diff and spot the one place that breaks under concurrency is worth enormously more than the person who can produce 400 lines.

And it compounds badly in the other direction: someone who never developed reading skill, in an environment where they write less code than any previous generation, will develop neither.

the thing I would change about how we teach#

Give students a real codebase and a bug report before you give them a blank file.

Have them find it. Have them explain what the system does. Have them make a one-line fix and defend why it is correct.

That is the actual job. We spend four years preparing people for the part of it that machines now do well, and zero hours on the part that they do not.

For that problem it is excellent. For the problem most teams actually have — a colleague you sit next to made a change to a system you both understand — it is a poor fit that we have collectively stopped noticing.

what it optimizes for#

Asynchrony. Nobody has to be available at the same time. Enormously valuable across time zones, and a real cost when the two people are online simultaneously and could have resolved it in four minutes.

A permanent record. Genuinely useful and undervalued. The PR discussion is frequently the only place a design decision's rationale is written down.

Gatekeeping. The change cannot land without approval. Necessary for untrusted contributors, and a substantial tax when applied uniformly to trusted ones.

what it costs#

Latency. The median PR spends most of its life waiting. Not being reviewed — waiting to be reviewed. That latency is the single largest contributor to cycle time in most organizations, and it is almost entirely queueing rather than work.

Batching. Because review has fixed overhead, people batch changes to amortize it. Bigger PRs are exponentially harder to review well, which produces worse review, which produces more defects. Everyone knows this and everyone does it anyway, because the incentive is structural.

Performative approval. Review quality falls off a cliff past a few hundred lines. Beyond that, "LGTM" means "I skimmed it and I trust you," which is sometimes a fine thing to mean and is not what the approval button claims.

Ownership diffusion. "It was reviewed" becomes a substitute for "someone understood it." Two people who each 60% understand a change do not add up to one person who understands it.

the agent problem#

This is the part that has changed and why the framing needs revisiting now.

If an agent produces five pull requests in an hour and a human can meaningfully review two, you have not increased throughput. You have created a queue with a human at the front of it, and the pressure to approve faster is enormous.

The failure mode is predictable: review quality degrades to a rubber stamp, because the alternative is being the bottleneck that everyone can see. The metrics look great. The defect rate does not, six months later.

We do not have a good answer to this yet. Some things that seem to help:

• Require the agent to explain its reasoning in the PR body, specifically the decisions it made and the alternatives it rejected. Reviewing a decision is faster than reconstructing it from a diff.
• Make tests the primary gate and review the secondary one. If the test suite is strong, review can focus on design rather than correctness.
• Review the interface, not the implementation, for agent-generated code. The interface is where the expensive mistakes live.
• Reject on size. A machine can produce a 2,000-line diff effortlessly. Say no. It is not a favor to accept it.

the alternatives worth trying#

Pair or ensemble programming. Review happens continuously, at the moment of writing, by someone with full context. Zero latency, better knowledge transfer, and no queue. The cost is synchronous time, which is real, and which teams consistently overestimate relative to the cost of PR latency.

Trunk-based with post-commit review. Land it, review it after, revert if wrong. Requires strong tests, a fast revert path, and actual trust. Works extremely well where those exist and is a disaster where they do not.

Tiered review by risk. Not every change needs the same process. A typo fix in a comment and a change to the authentication path are both "a PR" today, and treating them identically is how the process becomes theater.

what I actually recommend#

Keep pull requests. Change three things:

1. Cap the size. A hard limit, enforced by tooling, with an override that requires a written justification. 400 lines is a reasonable line.
2. Set a review SLA and measure it. Not "we should review quickly." A number, on a dashboard, reviewed in the same meeting as uptime.
3. Make small PRs cheap. If opening a PR takes ten minutes of ceremony, people will batch. Automate the ceremony.

The tool is fine. The way it is applied to every change regardless of size, risk, or author is the problem, and that is a policy decision, not a technology one.