practiceEngineering & architecture

Code Review

A structured examination of a proposed code change by someone other than its author before or soon after integration.

Download Markdown (.md)

01What it means

Code review is the evaluation of a software change by one or more peers using a diff, supporting context, and relevant automated results. Reviewers assess whether the change improves the codebase and meets its intended behavior while considering design, correctness, tests, security, maintainability, and operational consequences. The review is a technical conversation, not merely an approval click.[1][2]

A technical conversation around one proposed change Context and automation prepare the diff for focused human judgment
  1. 01Focused changePurpose, context, evidence, and relevant risks
  2. 02Automated checksFormatting, static analysis, and repeatable tests
  3. 03Human reviewDesign, behavior, security, maintainability, operations
  4. 04Resolve findingsSpecific discussion, revision, or synchronous collaboration
  5. 05Approve + integrateRequired concerns addressed and code health improved

Review complements testing, threat modeling, production observation, and ownership; a rubber-stamp approval is not a meaningful control.

02Why it matters

Review can detect defects and risky assumptions before they spread, while sharing knowledge about systems and engineering standards. It also creates an opportunity to improve naming, simplify designs, and verify that tests explain important behavior. Over time, thoughtful review can reduce single-person ownership of critical code.

03When to use it

Review changes that affect shared or production software, adjusting depth to risk. A small documentation correction needs less scrutiny than authentication logic, a database migration, or a public API. Pair or mob programming may provide continuous review, but teams should still preserve any evidence and independent approvals required by policy.

04How it works

  1. Keep the change focused and provide its purpose, context, testing evidence, and relevant risks.
  2. Let automation handle repeatable formatting, static analysis, and basic test checks where possible.
  3. Review the design and behavior before spending attention on minor presentation details.
  4. Write specific, respectful comments that distinguish blocking problems from optional suggestions.
  5. Resolve questions through discussion or synchronous collaboration when text becomes inefficient.
  6. Approve only when the change improves overall code health and required concerns are addressed.

05A practical example

Example

A developer proposes caching customer permissions. The reviewer notices that invalidation covers role changes but not account suspension. They request a test for suspension, suggest a bounded cache lifetime, and ask for a metric on stale decisions. The revised change remains small and documents the operational trade-off.

06Where it breaks

Reviewers have limited time and may miss subtle defects, especially in large or unfamiliar changes. Review can become a bottleneck, reinforce status differences, or reward stylistic debate over meaningful risk. It does not replace automated testing, threat modeling, production observation, or clear ownership, and rubber-stamp approvals provide little protection.

Common mistakes

  • Submitting changes so large that reviewers cannot build a reliable mental model.
  • Focusing on formatting that automated tools could enforce.
  • Using vague or personal criticism instead of explaining technical impact.
  • Allowing review queues to grow until feedback arrives after context is lost.

07Sources

  1. Google Engineering Practices Documentation: Code ReviewGoogle · Institutional engineering guideGoogle Engineering Practices Documentation: Code Review
  2. The Standard of Code ReviewGoogle · Institutional review standardThe Standard of Code Review
View saved topics

Start typing to search titles, definitions, categories, and frameworks.