Skip to content
All posts

SERIES · 20 POSTS · 124 MIN

The Craft of Code Review

The hands-on series: how to review large pull requests without drowning, what to look for in migrations, APIs, frontend changes, tests and refactors, and how to write feedback that gets acted on instead of resented.

Start with Why are pull requests so hard to review?

READING ORDER

Read it in order.

  1. 01Why are pull requests so hard to review?Pull request review is slow because reading code is harder than writing it, and the tools make it worse. The four real causes, and what actually helps.6 min
  2. 02How to review large pull requests without losing your mindA practical, step-by-step method for reviewing large pull requests: triage the files that matter, review in passes, and keep your place in a 40-file diff.7 min
  3. 03How big should a pull request be?The research-backed answer on pull request size: under ~400 changed lines, smaller is better. Where the number comes from, when to break it, how to split.7 min
  4. 04Author self-review: the cheapest code review you’re not doingSelf-review your pull request before requesting eyes: catch the cheap defects at the cheapest point and halve reviewer round-trips. A five-minute pass.6 min
  5. 05Nitpicks are killing your code reviewCode review nitpicking crowds out logic review, demoralizes authors, and slows merges. Automate the nits, label the rest, save attention for what matters.6 min
  6. 06Re-reviewing a PR after changes: the interdiff problemHow to review changes since your last review: the interdiff problem, force-push pain, git range-diff, and commit-scoped diffs that keep threads intact.6 min
  7. 07Atomic commits make reviewable PRsStructure a pull request as a sequence of atomic commits and reviewers can read it like chapters. The craft of commit-by-commit review, and the squash debate.6 min
  8. 08Risk based code review: tier your rigor by blast radiusRisk based code review tiers rigor by blast radius, longevity, and ownership. A concrete four tier model, how to encode it, and the everything is critical trap.8 min
  9. 09A code review checklist that fits in your head: three passes, seven questionsA code review checklist that fits in your head: three passes, seven questions worth asking every time, and when checklists turn into box-ticking.6 min
  10. 10A security code review checklist for auth, payments, and input handlingA security code review checklist for auth, payments, and input handling: trust boundaries, authz on new paths, secrets, and a two-reviewer rule.7 min
  11. 11How to review database migrationsHow to review database migrations: verify the down path, lock behavior on big tables, deploy order, and backfills before a one-line ALTER hurts you.6 min
  12. 12How to review API changes without breaking clientsHow to review API changes as contract changes: additive vs breaking, nullability and error-shape traps, versioning, deprecation, and generated clients.6 min
  13. 13How to review frontend pull requests beyond looks fineHow to review frontend pull requests beyond looks fine: the four UI states, race conditions, accessibility basics, bundle cost, and when to pull the branch.6 min
  14. 14How to review test code so that green means somethingHow to review test code so green means something: ask if the test can fail, assert requirements over implementation, and catch flakiness smells in the diff.6 min
  15. 15How to review a refactor when the claim is no behavior changeHow to review a refactor: treat no behavior change as a claim needing evidence, use commit structure and untouched tests, and catch sneaked-in edits.6 min
  16. 16How to review dependency updates without reflex-mergingHow to review dependency updates without reflex-merging: tier Renovate and Dependabot PRs by risk, read changelogs, and watch new transitive packages.6 min
  17. 17How to review infrastructure as code and config changesHow to review infrastructure as code: why small config diffs hide huge blast radius, plus a checklist for env scoping, secrets, defaults, and rollback.6 min
  18. 18Code review comments that land: examples, rewrites, and severityCode review comments examples that actually land: before and after rewrites, severity prefixes, questions over verdicts, and praise that teaches.6 min
  19. 19When to request changes in a code review, and when to approve with commentsWhen to request changes in code review: block only on correctness, security, or irreversible design, and make approve with comments your default verdict.5 min
  20. 20How to do your first code review without pretending to know everythingHow to do your first code review: pick small PRs, read the description before the diff, ask real questions, and know exactly what your approval means.6 min

More on review,in the archive.

Free on your personal account. Teams are $7.99 per seat / month billed yearly, or $9.99 monthly, with Pyor AI included, and start with a 30-day trial, no card.