Code Review Best Practices

Status: public · Confidence: medium (0.725) · Basis: verified_sources

## TL;DR

Good code review protects code health while keeping useful work moving. Reviewers should check design, behavior, complexity, tests, readability, and documentation, then leave actionable comments that explain the reason for any requested change.

## Core Explanation

The review target is not perfection. The practical standard is whether the change improves the system and does not add unnecessary risk. For AI coding agents, this matters because the reviewer must verify the patch against the project contract rather than trust a plausible explanation from the agent.

Use a compact review order:

- read the goal and affected modules;
- run or inspect relevant tests;
- check design fit before line-level style;
- verify error handling, data boundaries, and migration effects;
- ask for simpler code when complexity is speculative;
- separate blocking issues from optional improvements.

## Source-Mapped Facts

- Google's engineering practices say reviewers should generally favor approval once a change definitely improves the overall code health of the system, even if it is not perfect. ([source](https://google.github.io/eng-practices/review/reviewer/standard.html))
- Google's code review guidance lists design, functionality, complexity, tests, naming, comments, style, consistency, documentation, and every line as review concerns. ([source](https://google.github.io/eng-practices/review/reviewer/looking-for.html))
- Google's code review speed guidance says one business day is the maximum time it should take to respond to a code review request. ([source](https://google.github.io/eng-practices/review/reviewer/speed.html))
- Google's comment-writing guidance summarizes code review comments with the instruction to be kind. ([source](https://google.github.io/eng-practices/review/reviewer/comments.html))
- GitHub documentation says a pull request reviewer can submit comments, approve the changes, or request changes. ([source](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request))

## AI Agent Review Notes

When reviewing agent-generated patches, put extra weight on behavioral contracts. Confirm that the patch did not change unrelated files, generated artifacts, secrets, or deployment configuration. Require source citations when the patch depends on external API behavior, and prefer narrow follow-up patches over broad speculative cleanup.

## Further Reading

- [The Standard of Code Review](https://google.github.io/eng-practices/review/reviewer/standard.html)
- [What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html)
- [Speed of Code Reviews](https://google.github.io/eng-practices/review/reviewer/speed.html)
- [How to write code review comments](https://google.github.io/eng-practices/review/reviewer/comments.html)
- [Reviewing proposed changes in a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request)

## Related Articles

- [AI for Static Analysis: Automated Bug Detection, Code Review, and Vulnerability Scanning](../../ai/ai-static-analysis.md)
- [Docker Security Best Practices](../docker-security-best-practices.md)
- [OAuth 2.0: Authorization Framework and Security Best Practices](../oauth-2-0-authorization-framework-and-security-best-practices.md)