Code review: standards and guidelines

The goal of code review is continuous improvement, not perfect code. Code review protects and improves the health of the codebase over time while allowing engineers to make progress.¹

Author responsibilities

Explain what changes and why. Include relevant tests and ensure required automated checks pass before requesting final approval. Tests and check results supply the verification evidence; a separate test report is not required.²

Behavior changes must have appropriate automated tests or other executable verification. Coverage alone is insufficient. A change that cannot meet this verification requirement needs an authorized exception through the applicable change-management process.

The author remains responsible for the change and must understand its implementation and tests, including AI-generated work. Bot-authored changes need an accountable person or team. Early design feedback and draft reviews may begin before checks pass.

Reviewer responsibilities

Understand the code in the scope you approve and enough surrounding context to support the decision. Involve specialized reviewers when necessary. Assess:³

• Design and system fit: whether the change belongs in the system, integrates cleanly, and improves overall code health.
• Behavior and consequences: whether it does what is intended and has acceptable effects for users, data, security, compatibility, concurrency, and operations where relevant.
• Complexity and maintainability: whether the code is no more complex than necessary, understandable, appropriately named, and solving today’s problem rather than speculative future needs.
• Test and verification quality: whether tests are correct, useful, and would expose plausible failures; whether automated checks establish the properties they claim to establish.
• Clarity and documentation: whether important assumptions are visible and the code and documentation will remain understandable to future engineers.

Review test changes as part of the implementation. Weakened assertions, skipped tests, changed snapshots, and changed expectations need a sound reason. Raise material defects or concerns you identify even when required checks pass.

Routine regression testing belongs in automated verification, not the reviewer’s approval duties. Assess the evidence rather than repeat checks enforced by tools. Targeted validation addresses a specific question and has an explicit owner.

Approval decision

Favor approval once a change clearly improves overall code health, meets applicable standards, has adequate verification, and has no unresolved material concern—even when it is not perfect.¹

Do not require polish beyond what is necessary for code health. Technical facts, data, and established engineering principles take precedence over personal preference. When multiple approaches are materially equivalent, accept the author’s choice.

Review comments that affect approval should make their blocking status explicit. The concern, not the comment format, determines whether a comment may block.

A question can block approval when its answer is necessary to assess a material concern. State the uncertainty and why it matters. Do not block on speculative concerns without a credible failure mode, unmet requirement, or evidence gap. Resolve disagreements through technical evidence and the relevant owner.

Approval requirements

Changes must satisfy applicable required checks, review requirements, and ownership requirements before merge. An approval applies only to the scope and revision actually reviewed; material changes require re-evaluation under the applicable rules.

The Approval Policy defines when human review is required and when an authorized automated approval route may satisfy a review requirement.

Reference

Targeted validation and the QA boundary

Usability, accessibility, visual, or exploratory validation can address a question that automated checks do not adequately answer. Record its purpose, owner, and findings. Screenshots or one successful manual run do not provide repeatable regression protection.

Correctness remains part of review. Missing edge cases, incorrect expectations, security issues, and unsafe interactions are legitimate concerns; request the relevant correction or evidence rather than acting as the routine test runner.³

Scope and exceptions

This standard applies to changes submitted through the review process, including code, tests, configuration, infrastructure, dependencies, documentation, and delivery tooling.

Exceptions follow the applicable change-management or emergency procedure. The record identifies the unmet requirement, authorization, and follow-up. When exception authority is unclear, the responsible control owner resolves it; uncertainty does not grant permission.

A failed required check blocks merge unless the applicable control permits an authorized exception. An ordinary approval is not an exception.

Must identifies a requirement. The Code Review Guidelines provide techniques and examples. Approval scope, reviewer counts, ownership requirements, and reapproval rules are defined by the applicable controls and change-management rules.

The goal is continuous improvement, not perfect code. A good review improves code health while allowing engineers to make progress. Understand the intended behavior, read the implementation and tests, examine relevant check results, and make a decision.¹

Use the techniques relevant to the change. The Standard defines responsibilities and the approval threshold; the Approval Policy defines merge and automation requirements.

For authors: prepare a reviewable change

Explain the outcome, not just the edit. “Prevent duplicate processing on retries” is more useful than “replace a loop with a map.” State what should change and what must stay the same. Link relevant requirements and design decisions.

Keep the change coherent. Separate broad formatting and unrelated cleanup from behavior changes where practical. Split by understandable purpose, not an arbitrary line-count target. Keep changes together when they need shared correctness or compatibility context.

Let tests and checks provide the evidence. Do not transcribe test cases, coverage figures, or automated check results into the description. Link external evidence or explain a verification limitation when it is not already available to reviewers.²

Make the code explain itself. Prefer clear code, names, and documentation over review-only explanations. If the change is difficult to understand, simplify it where practical instead of relying on prose that disappears after the review.³

For reviewers: answer three questions

Understand the code you approve, not just the summary. Review the assigned scope closely, and bring in qualified domain reviewers when a change crosses specialized areas.³⁴

Start with the change description and the overall design. Read the main behavior changes, then follow relevant callers, contracts, tests, and operational context. Review details after understanding what the change is trying to accomplish.

State any limits on your review: excluded files, unexamined behavior, or specialist questions still awaiting an owner. A partial review is not whole-change approval.

If the code is unnecessarily difficult to understand, ask for simplification rather than relying on a review explanation that future engineers will not see. If you are not qualified to review an important part of the change, involve someone who is.

Favor progress over perfection

Favor approval when the change clearly improves overall code health, satisfies applicable standards, has adequate verification, and has no unresolved material concern. There is no requirement that a change be perfect before it can merge.¹

Nits, optional improvements, personal preferences, and unrelated cleanup do not block approval. Leave them as non-blocking feedback and approve the change. If several approaches are materially equivalent under the applicable engineering principles, accept the author’s choice.

Do not manufacture blockers from abstract uncertainty. A blocking concern should identify a credible failure mode, an unmet requirement, materially inadequate verification, or a concrete degradation in code health. When uncertainty itself is material, explain what is unknown, why it matters, and what evidence would resolve it.

Do not trade code health for speed, but do not add avoidable review latency either. If you cannot perform the needed review, help route the change to someone who can.⁵

Giving feedback

Discuss the code and its consequences, not the author’s character or competence. Distinguish a question from a correction, explain the reason, and leave room for information you may have missed.

Make it actionable

State the concern, its consequence, and the outcome needed to resolve it. Explain the engineering reason when it is not obvious. Make blocking intent explicit and apply the Standard’s approval threshold. Ask for specific evidence rather than an unbounded “add more tests.” Approve when only optional improvements remain; a review with no findings is valid.

Positive feedback is useful when it reinforces a practice worth repeating.³

Make intent clear

Clarity matters in both directions: review comments should make the reviewer’s intent clear, and change metadata should make the author’s intent clear.

Conventional Comments provides a shared vocabulary for review feedback, including whether feedback is blocking or non-blocking. It can reduce ambiguity between required changes, questions, suggestions, and nits.⁶

Conventional Commits provides structured metadata describing the purpose and scope of a change, making change history easier for people and tooling to interpret.⁷

These conventions are encouraged, not required by this guide. They communicate intent; they do not change the approval threshold. A comment blocks only when the underlying concern meets the blocking threshold, and commit metadata does not establish correctness or safety. The published specifications are authoritative for syntax.

AI-assisted development and review

The author remains responsible for understanding the code and tests. AI can help find call sites, suggest failure cases, and identify possible defects. Check consequential claims against the implementation and requirements; a fluent explanation is not verification.

Implementation, tests, and explanation produced together can share the same wrong assumption. Look for an independently established expected result. Neither human nor AI authorship makes a change safe by itself.

AI-assisted review should follow the same blocking threshold as human review. Do not manufacture findings because a review tool is expected to produce output. If human peer review is required by policy, AI output does not satisfy that requirement unless the approval policy explicitly authorizes it.

Examples and reference

Assessing test quality

Ask where an expected result comes from and what wrong behavior would make the test fail. For a bug fix, check whether the regression test would fail on the original defect. Examine relevant boundaries: another tenant, a retry, a missing field, a partial failure, or a precision limit. Match the test expectations to the change rather than requesting every imaginable case.

For example, suppose the implementation and test both compute a charge with amount * rate. Both may omit a required rounding rule. The useful review request is for independently specified expected amounts and relevant precision cases—not manual calculation of every possible charge.

Changed snapshots, deleted assertions, added skips, broader mocks, and wider tolerances need an explanation because they change what the suite permits. Tests should be correct, sensible, useful, and capable of failing when production behavior is broken.³

Coverage shows execution, not whether an assertion is useful. Contract, property, and mutation tests are options for strengthening evidence where appropriate; they are not required techniques for every change.

Questions for consequential changes

Use the relevant questions; they are not required written sections. Specialist approval follows the applicable ownership and review requirements.

Change description template

## What and why
Intended outcome and context not apparent from the diff.

## Additional context (optional)
Non-obvious constraints, rollout or recovery considerations,
manual validation, or known verification limitations.

Omit the optional section when it adds no information. Do not duplicate tests or check results in the description.

A change may merge only after its applicable verification, review, ownership, and policy requirements are satisfied. Human approval and automated approval are distinct mechanisms; automation may satisfy a review requirement only where the applicable policy explicitly authorizes it.

Before merge

Where a process requires a risk assessment or classification, complete it and keep it current. It is an input to the approval process, not a substitute for direct evidence, required checks, ownership, or review judgment.

The Code Review Standard defines the human approval threshold. The approval mechanism does not change that standard of quality.

Human approval

Human approval means the reviewer considers the change acceptable within the scope reviewed. The reviewer must have enough context and expertise to support that decision, or involve additional qualified reviewers for the portions they cannot assess.

An approval applies to the revision and scope actually reviewed. Material changes require re-evaluation according to the applicable reapproval rules.

Automated approval

Automated approval requires explicit authorization under the applicable review and ownership controls. The route must define its scope, required evidence, decision rules, and accountable owner before it is used in place of required human review.

The evaluator must check the actual change and trustworthy evidence. Labels, metadata, a numeric score, author identity, coverage percentage, or an AI recommendation may be inputs, but none establishes approval eligibility by itself. Required checks, ownership conditions, and review requirements outside the authorized substitution remain mandatory.

Automated decisions must be distinguishable from human review and identify the evaluated revision, decision reasons, relevant evidence, and applicable rule or model version. A change cannot authorize itself by changing the approval rules used to evaluate it. Automated review may satisfy a narrowly defined review requirement while ownership remains a separate control.⁸

For a weighted or learned model, favorable signals must not silently cancel mandatory controls. Changes to the model or thresholds may tune decisions only within the authority already granted to the automated route; expanding that authority requires the applicable control-change process.

Reference

Decision records and changes after review

The change, tests, automated check results, approvals, and review discussion form the decision record. Preserve material findings and their resolution there; include external or manual evidence when it is not otherwise available.

Checks and approvals must apply to the change being merged. Obtain any required reapproval when scope or consequences materially change. Retain decision records according to the applicable record-retention controls.

A resolved discussion or absence of marked blocking comments does not substitute for a required approval. Clarify ambiguous approval intent rather than assume a concern is resolved.

Outcome analysis for approval automation

For an authorized automated route, evaluate both attributable production failures and material concerns identified through sampled review. An absence of reported incidents is not sufficient evidence that decisions were appropriate.

Record the number and type of evaluated changes, the decision rules or model version, and the observation period alongside findings. Account for delayed reports and incomplete observation. Compare similar change populations rather than raw automated-versus-human failure rates, since the routes may intentionally select different kinds of changes.

Material unsafe automatic approvals require investigation and, when warranted, restriction or suspension of the affected route. An approval-control bypass requires immediate containment rather than waiting for routine recalibration.