Code Review Best Practices
The core goal of Code Review is to confirm the intent of changes, behavioral boundaries, risks, and long-term maintenance costs.
A good review finds bugs and helps the team maintain shared engineering judgment.
Review Order
We recommend reviewing in this order:
- Is the PR goal clear?
- Is the diff scope focused?
- Do behavioral changes match expectations?
- Are tests and validations reliable?
- Are error handling and boundary conditions complete?
- Are naming, structure, and style consistent with existing code?
- Are security risks and rollback paths clear?
What Reviewers Should Ask
- Is the problem solved by this change clear?
- Are there any unrelated changes?
- Is the blast radius explained?
- Do tests cover the actual behavior?
- Do naming and structure match the existing project?
- Is it easy to roll back if issues occur?
Review Standards
Google’s public Code Review documentation emphasizes that the goal of code review is to ensure the codebase remains healthy and continues to improve over time.
This leads to a practical judgment: if a PR clearly improves the system and introduces no obvious risks, reviewers should lean towards approving it, rather than delaying indefinitely over non-critical details.
Teams can categorize comments into three types:
- Blocking issues: correctness, security, compatibility, obvious maintenance risks.
- Suggestion issues: naming, local structure, readability improvements.
- Optional issues: stylistic preferences, minor optimizations, non-essential content for the current PR.
What Authors Should Do
- Self-review the diff before opening a PR.
- Proactively explain risks and validation methods.
- Provide additional context for complex designs.
- Respond to review comments item by item.
- Do not throw large, unexplained changes directly at reviewers.
How to Review AI-Generated Code
Pay special attention to AI-generated code:
- Is the diff too large?
- Did it silently change behavioral boundaries?
- Are tests merely superficial coverage?
- Did it introduce unnecessary abstractions?
- Are unrelated formatting changes or generated files mixed in?
For details, see AI-Generated Code Review.
Governance Insights from Large Projects
Kubernetes’ OWNERS model splits reviews into two layers: reviewers and approvers. The former focus on code quality, while the latter focus on overall acceptance criteria, compatibility, and long-term impact.
Enterprise teams can learn from this tiering: general reviewers are responsible for finding specific issues, while code owners or module leads are responsible for final approval.
Templates
See Code Review Checklist.
Extended Reading