Google’s Code Review Standards: A Practical Guide for Developers

Google Code Review Standards

Code Review (CR) aims to continuously improve the quality of Google's codebase. Reviewers must balance progress for developers with maintaining overall code health, ensuring changes are not overly complex, over‑engineered, or introduce regressions.

Guidelines

CR should teach developers new language, framework, or design concepts. Educational comments should be prefixed with nit: if they are not essential for meeting the standards.

Principles

Style guides are authoritative; follow existing project style or accept the author's style if none exists. Design decisions should be based on solid principles and data, not personal preference. When no rule applies, reviewers may ask authors to align with the existing codebase as long as it does not degrade overall quality.

Resolving Conflicts

When conflicts arise, developers and reviewers should first seek consensus using the guide. If consensus is difficult, hold a face‑to‑face meeting and record the outcome in the CL comments. If still unresolved, escalate to team leads or technical managers.

What to Look for in a CR

Design : Assess overall architecture, interaction between code sections, integration with the system, and timing of the change.

Functionality : Verify the change meets the author's intent, benefits users, and includes adequate testing, especially for UI changes or concurrent code that could cause deadlocks.

Complexity : Ensure code is not overly complex or over‑engineered; avoid unnecessary generalization.

Testing : Require appropriate unit, integration, and end‑to‑end tests; ensure tests are meaningful and maintainable.

Naming : Names should clearly convey purpose without being overly long.

Comments : Comments must explain *why* something is done, not *what* the code does.

Style : Follow the language‑specific style guide; use nit: for minor style suggestions.

Documentation : Update README, g3doc, or generated docs when CL changes affect build, test, or release processes.

Every Line of Code : Review all non‑generated code thoroughly; request clarification for complex sections.

Context : View the whole file when needed; consider the impact on the entire system.

Advantages : Praise good practices and correct implementations, not just point out mistakes.

Marking each commit's purpose helps reviewers quickly understand changes.

Don’t hesitate to give praise when appropriate!

Summary

Reviewers own the quality of the CL and should aim for continuous improvement rather than perfection.

CR should provide guidance and educational value.

Code style must be consistent with existing guidelines.

When conflicts cannot be resolved, involve larger team discussions with leaders.

How to Browse a CL

Start with a high‑level view: read the CL description and purpose.

Identify and review the most critical parts first.

Proceed through the remaining changes in a logical order, often following the tool’s file sequence.

Review Speed

Fast reviews keep the team’s overall velocity high, prevent developer frustration, and maintain code quality. Aim to respond within one workday, and prioritize quick, polite feedback over lengthy delays.

Cross‑Timezone Review

Reply while reviewers are still in office; if not, ensure a response before their next workday.

LGTM Comments

Reviewers may give LGTM or Approval even with minor unresolved comments if they trust the author will address them, or if the comments are insignificant.

Large Changes

Ask authors to split massive CLs into smaller, reviewable units. If splitting isn’t possible, provide high‑level design feedback and request improvements.

Improving Review Process Over Time

Strict adherence to these guidelines leads to faster, higher‑quality reviews as developers internalize good practices.

Handling Urgent Situations

Only relax standards for genuine emergencies; otherwise, maintain the full review rigor.

Writing Review Comments

Consider whether the developer might be correct; explain your reasoning politely.

Avoid causing unnecessary frustration; focus on constructive, respectful communication.

Address new issues before merging unless it’s an emergency; use TODO comments linked to tracked defects when needed.