Skip to content

Code Review

Core Idea

Code review is a structured quality and learning workflow, not a gate for personal approval. Its job is to improve correctness, maintainability, and shared understanding before changes reach production.

This chapter is inspired by Best Kept Secrets of Peer Code Review by Jason Cohen, Steven Teleki, and Eric Brown. The main takeaway is practical: review quality drops when changes are too large or reviews are too fast.

Why Peer Review Works

A healthy review process provides four outcomes:

  • defect discovery before release
  • architecture and style consistency
  • knowledge sharing across the team
  • reduced long-term maintenance risk

Reviewing code also changes author behavior. When engineers know peers will read a change, they usually write clearer code, tests, and commit messages.

Review Workflow Design

Keep each review small

Large pull requests reduce reviewer attention and defect detection. Based on data discussed in the Cohen/Teleki/Brown paper, use these limits:

  • ideal review size: up to about 200 lines of code
  • hard upper bound: around 400 lines of code per review

If a change is bigger, split it into smaller, coherent slices.

Control review speed and duration

Reviewing too quickly lowers quality. Guidelines from the same study:

  • inspection rate target: below about 300 lines/hour
  • useful upper limit: below about 500 lines/hour
  • per-session duration: 30-60 minutes
  • hard limit: stop around 90 minutes and continue later

Require author context

Authors should not drop code with no framing. Each change should include:

  • intent and business context
  • risks and edge cases
  • test evidence and known limitations
  • explicit areas where deeper scrutiny is needed

Use a consistent checklist

A small checklist keeps reviews focused and repeatable. Example checklist categories:

  • correctness and edge cases
  • reliability and failure handling
  • security and input validation
  • observability (logs, metrics, traces, error context)
  • maintainability and readability
  • testing scope and quality

Close the loop

A review is complete only when:

  • feedback is addressed or explicitly resolved
  • non-trivial comments are tracked to closure
  • follow-up tasks are filed if work is deferred

Review Comment Quality

High-quality comments are:

  • specific (point to exact behavior or line)
  • actionable (describe what should change and why)
  • contextual (connect to design, risk, or user impact)
  • respectful (critique code, never the person)

Low-value comments are vague ("this looks odd"), purely stylistic nitpicks with no shared standard, or drive-by approvals with no evidence of review.

Metrics That Improve the Process

Track process health, not individual rank. Useful team-level metrics include:

  • review size distribution
  • review turnaround time
  • rework rate after review
  • escaped defects by category
  • percentage of reviews with test-impact discussion

Avoid using these metrics for individual performance scoring. If metrics become punitive, review quality and honesty decline.

Common Anti-Patterns

  • mega pull requests reviewed in one pass
  • superficial approvals ("LGTM") with no meaningful feedback
  • checklist sprawl that reviewers ignore
  • waiting days to review high-priority changes
  • focusing only on style while skipping correctness and risk
  • treating review as ownership conflict instead of collaboration

Practice Checklist

  • Keep changes reviewable in small, coherent units.
  • Enforce review size and session length guardrails.
  • Require author context and test evidence in every change.
  • Use a concise, stable checklist for all reviews.
  • Prioritize correctness, risk, and maintainability over personal preference.
  • Make comment quality standards explicit to the team.
  • Track team-level review metrics and inspect trends monthly.
  • Separate coaching from approval mechanics when possible.
  • Resolve all substantive comments before merge.
  • Periodically recalibrate standards with examples of good reviews.

See References for complete APA-style bibliographic entries used on this page.