rgoussu.dev
rgoussu@goussu: ~/library/engineering-practice
❯ ~/library/engineering-practice cat code-review.md

Code review

# Review as a practice — what it's actually for, how to give and receive it well, and the process mechanics that keep it fast and humane.

Conceptsaved 2026-08-08 #code-review#craft#collaboration#process

Overview

Code review is the highest-leverage team practice in software — not primarily for catching bugs (tests do that better) but for knowledge spread, design feedback while change is still cheap, and maintaining a shared bar for the codebase. Done badly it's a bottleneck and a morale sink; the difference is almost entirely process mechanics (size, latency, tone) rather than reviewer brilliance.

Key points

  • Know what review is for: readability and maintainability, design fit, knowledge transfer, and collective ownership. It is the worst tool for catching what a linter, formatter, or test can catch — automate those out of the conversation entirely so humans discuss only what humans must (CI/CD gates first, review second).
  • Small changes or nothing works: review quality collapses with diff size ("LGTM" is what 2,000-line PRs receive); a few hundred lines with a clear narrative is the target — stacked/chained PRs for big features. The author's description (what, why, how to review it, what's deliberately out of scope) is half the review.
  • Author obligations: self-review the diff first (you'll catch a third of the comments yourself), respond to every comment (fix, or explain — silence is neither), and treat pushback on your code as pushback on the code, which it is.
  • Reviewer obligations: comment on the code, never the coder ("this function could…" not "you didn't…"); distinguish severity explicitly — blocking vs. nit: vs. question — so the author knows what matters; offer the why (a principle or a link, e.g. clean code) not just the verdict; and approve when it's better and good enough, not when it's how you'd have written it. Google's standard is the reference: prefer continuous improvement over perfection.
  • Latency beats thoroughness: a review turnaround measured in hours keeps work flowing and diffs small; one measured in days causes the giant PRs everyone then complains about. Treat review as interrupt-priority work; a same-day SLO changes team dynamics more than any checklist.
  • Alternatives on the dial: pair programming is continuous review (no artifact, no latency); ensemble/mob for gnarly shared-context work; post-merge review for trusted trivial changes (trunk-based shops). The practice is negotiable, the feedback loop isn't.
  • To explore: review checklists per change type, ownership models (CODEOWNERS), measuring review health (time-to-first-review, rework rate), AI-assisted review as first-pass filter.

Practice

  • Severity-labeling pass (source) — rewrite your last ten review comments in the labeled form (blocking / suggestion / nit / question, with the why); teaches explicit severity and comment-on-the-code phrasing as a habit, not an intention.
  • Reviewer-guide shadow review (source) — pick a merged open-source PR you didn't write, review it cold against Google's reviewer standard, then compare with what the real reviewers said; teaches calibration — what you catch, what you miss, what you'd wrongly block.
  • Split-the-monster drill (source) — take one of your own oversized past PRs and re-plan it as a stacked chain of small, individually reviewable PRs with a narrative description each; teaches that small diffs are authored, not hoped for.
  • Join a PR review club (source) — Bitcoin Core's weekly club walks a real PR with maintainers: prepare, annotate, discuss; teaches review of unfamiliar, high-stakes code alongside people who do it at reference level.

Related