# Code Review

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

- Type: practice
- Domain: Engineering & architecture
- Level: Foundational
- Last reviewed: 2026-09-22
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/code-review/>)

## What 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.

## Why 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.

## When 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.

## How 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.

## A practical 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.

## Where 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.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/code-review/#visualization-code-review>)

## Sources

1. [Google Engineering Practices Documentation: Code Review](<https://google.github.io/eng-practices/review/>) — Google · Institutional engineering guide
2. [The Standard of Code Review](<https://google.github.io/eng-practices/review/reviewer/standard.html>) — Google · Institutional review standard

## Related topics

- [Trunk-Based Development](<https://wiki.soroush.uk/topic/trunk-based-development/>)
- [Pair Programming](<https://wiki.soroush.uk/topic/pair-programming/>)
- [Refactoring](<https://wiki.soroush.uk/topic/refactoring/>)
