Skip to content

Code review expectations

Code review is a conversation with a merge button on it. The point is not to prove the code is perfect — it is to catch the things one pair of eyes would miss, and to spread understanding of the change across more than the author. This page covers what happens inside a review; how it fits the merge cadence is on branching and pull request workflow.

Review quickly, narrowly, and with a bias to merge. The author owns correctness; the reviewer owns fit — does this change belong here, does it match the surrounding code, would the next person understand it? Small diffs, one round of comments, resolved within the hour.

  • Author self-reviews first. Read your own diff before requesting. Fix the typos and dead code the reviewer would have caught anyway.
  • One named reviewer. Not “the team”. Assign a person; escalate if they’re not around.
  • Under 200 lines of diff. A PR that fits in a coffee break gets reviewed in one. Split larger changes.
  • Review for fit and correctness — not style. A linter is faster and never gets tired. If it isn’t lint-enforced, it isn’t worth blocking a PR over.
  • Comments are questions or requests. “Why this over X?” or “Please extract this.” Not verdicts on the author.
  • Approve means “safe to merge as-is”. Not “safe once you address my nits”. If you’d want another look, request changes.
  • Author merges. They know when CI is green and the change is complete. The reviewer isn’t the gate; the review is.

Slow, wide-ranging reviews teach authors to write to the reviewer, not to the reader. Fast, narrow reviews teach them to write to the codebase.

The scope split matters: if the reviewer owns correctness, the author learns to lean on review as a safety net and stops testing. If the reviewer owns fit, the author still has to prove the change works — and the reviewer catches what only a second pair of eyes can catch (does this duplicate something two directories away, does the name mean what it says, is this the right layer).

Bias to merge is the counterweight to a subtle failure mode: a reviewer who blocks on preference produces a codebase shaped by whoever reviews most, not by the team.

Not every change needs a blocking review. Sort them:

  • Ship — trivial and low-risk (typo, comment, obvious refactor, dependency bump with green CI). Merge without review; post-hoc glance is enough.
  • Show — routine change the author is confident about. Merge, then broadcast — a channel post or an FYI reviewer. Catches problems without gating on approval.
  • Ask — uncertain, novel, or wide-blast-radius. Blocking review, and this is where the review SLA earns its keep.

Most changes are Ship or Show. If every PR is an Ask, the team has traded throughput for a false sense of safety — and the review SLA on branching and pull request workflow will not survive.

  • Flag: correctness bugs, security issues, missing tests for the behaviour that changed, names that mislead, dead code, duplicated logic a reader wouldn’t find.
  • Let go: stylistic preferences the linter doesn’t enforce, patterns you’d have written differently but aren’t wrong, refactors of code the PR only touched incidentally.
  • Blocking vs suggesting. Prefix non-blocking notes — nit:, suggestion:, question: — so the author knows what actually gates merge. Ambiguity here is what makes reviews slow.
  • Author moves on approval. Once the reviewer approves, further comments are suggestions unless they explicitly re-request changes.
  • Escalate quickly. A back-and-forth past three rounds is a call, not a comment thread. Pull in a third opinion or pair for ten minutes.
  • Disagree in the review, commit in the code. Once merged, the reviewer’s preference is not a grievance to relitigate.
  • Rubber-stamping. Approving without reading. The signal degrades for everyone.
  • Review as gatekeeping. Blocking merge until the author writes it the reviewer’s way. Fine for correctness; not fine for taste.
  • Waiting for green CI before opening the PR. Open it early — the reviewer’s queue moves in parallel with your build.
  • Nine-line, twelve-comment PRs. A ratio of comments to diff lines above ~1:5 is usually the reviewer’s problem, not the author’s.
  • “LGTM 🚀” on a 400-line diff. Either it was too big, or the review didn’t happen.
  1. Read the PR description first — and the ticket it points at. If you can’t tell what the change is trying to do in one paragraph, ask before reading the diff.
  2. Read the diff in one pass. Comments as questions, prefixed by severity.
  3. Pick one outcome: approve, request changes, or comment (for Show/Ask discussion without blocking).
  4. Return the review inside the SLA. If you can’t, hand it off.