Code Review

How to review code effectively, give actionable feedback, and build review processes that improve both code and teams.

Quick Reference

Review Goals (Priority Order)

Effective Comment Templates (Triple-R Pattern)

Structure every non-trivial comment as Request → Rationale → Result:

Comment Severity Labels

Label comments so the author knows what's required vs. optional:

Review Process

Before You Review

1. •Read the PR description — understand the why before judging the how
2. •Check the scope — is this PR a single logical change? Flag if too large
3. •Run the code — for non-trivial changes, check out and test locally
4. •Check tests — are new behaviors covered? Do existing tests still pass?

During Review

Focus on one pass per concern to avoid cognitive overload:

1. •First pass: Correctness — Does the logic handle all cases? What breaks?
2. •Second pass: Design — Does this fit the codebase architecture?
3. •Third pass: Everything else — Naming, tests, docs, edge cases

After Review

• •Summarize — leave a top-level comment with your overall assessment
• •Be explicit about approval — "Approved with nitpicks" vs. "Needs changes before merge"
• •Follow up — check that requested changes were addressed (don't rubber-stamp re-reviews)

PR Best Practices (For Authors)

The PR Contract

Every PR should communicate:

Size Guidelines

Research shows reviewer attention drops sharply after ~400 lines. A 2000-line PR gets "LGTM" because nobody can review it properly.

Self-Review Checklist (Before Requesting Review)

• • PR description explains the why, not just the what
• • Changes are a single logical unit (one concern per PR)
• • Tests cover new behavior and edge cases
• • No debug code, commented-out blocks, or TODOs without tickets
• • Naming is clear and consistent with codebase conventions
• • No secrets, credentials, or PII in the diff

Team Working Agreement (TWA)

A Team Working Agreement (TWA) is a collaboratively created document that sets shared expectations for how the team does reviews. Create one together — never impose it top-down.

TWA Template

Review Cadence

Blocked PRs block features. Establish review rhythms:

• •SLA target: First response within 4 hours (business hours)
• •Review windows: Dedicated review time (e.g., first hour of day)
• •Rotation: Distribute reviews to avoid bottlenecks on senior devs
• •Escalation: If a PR has no reviewer after N hours, auto-assign or notify

Review Automation

What to Automate vs. What Needs Human Judgment

Rule: If a review comment could be written by a regex, it should be automated. Free human reviewers for judgment calls.

Automation Layers

AI-Augmented Code Review

AI review tools are rapidly maturing (2025-2026), but the collaboration model matters more than the tool choice.

The AI-Human Review Partnership

AI is a reviewer, not an approver. AI catches what humans miss (patterns across thousands of lines). Humans catch what AI misses (intent, context, organizational knowledge). Neither replaces the other.

What AI Catches Well

• •Common bug patterns (null derefs, off-by-ones, resource leaks)
• •Style violations and inconsistencies
• •Missing error handling
• •Test gaps and edge cases
• •Security vulnerability patterns (injection, XSS, auth issues)
• •Code duplication across files

What AI Misses

• •Whether the code solves the right problem
• •Architectural fit with the broader system
• •Business rule correctness
• •Naming quality and abstraction appropriateness
• •Institutional context ("we tried this before and it failed because...")
• •Whether the change aligns with the team's roadmap

AI Review Pitfalls

AI-Generated Code Review

Code written by AI requires more review rigor, not less:

• •AI-generated code has 1.75x more logic errors than human code
• •45% of AI-generated code contains security vulnerabilities
• •Authors must understand and explain every line — "the AI wrote it" is not a defense
• •Require proof (tests, manual verification) before review begins

(see code-quality-foundations -> Code Should Work, Code Should Keep Working)

Review Antipatterns

The Eight Review Antipatterns

(see code-antipatterns -> Pattern Recognition)

Sometimes you need to bypass normal review. Have a pre-agreed protocol:

Rules for emergency bypasses:

1. •Never skip review silently — always document
2. •Retroactive review is mandatory, not optional
3. •If you bypass more than once a month, your process has a deeper problem

Pair and mob programming can complement or partially replace traditional async review:

Pair/mob sessions don't eliminate the value of a fresh-eyes review, but they reduce the need for extensive async feedback because design discussions happened in real time.

Decision Tables

"What Should I Focus on in This Review?"

"Should I Approve This PR?"

Checklists

Reviewer Checklist

• • PR description explains intent clearly
• • Changes are appropriately scoped (single concern)
• • Logic handles edge cases and error paths
• • New behavior has test coverage
• • No security concerns (auth, injection, data exposure)
• • Naming and abstractions fit the codebase
• • No performance regressions in hot paths
• • Comments use severity labels (blocker/suggestion/nitpick)

Review Culture Health Check

• • Average first-response time < 4 hours
• • Reviews include praise, not just criticism
• • Junior developers review senior developers' code (both directions)
• • Disagreements resolved by TWA standards, not authority
• • Automation handles style enforcement (humans focus on design)
• • Emergency bypasses are documented and retroactively reviewed

See Also

• •code-quality-foundations — Quality pillars and goals that reviews enforce (see code-quality-foundations -> The Six Pillars)
• •code-antipatterns — Common patterns to watch for during review (see code-antipatterns -> Pattern Recognition)
• •code-readability — Readability standards to apply in review (see code-readability -> Naming and Structure)
• •code-testing-quality — Evaluating test quality during review (see code-testing-quality -> Test Strategy)