Google processes tens of thousands of code changes every day across a codebase of hundreds of millions of lines. The secret isn't magic tooling — it's a documented, principled approach to code review that any team can adopt.
In 2019, Google open-sourced its internal Engineering Practices documentation — the same guides used by its 25,000+ engineers. This article distills those principles into an actionable playbook, adapted for teams using GitHub Pull Requests (PRs) instead of Google's internal "Change Lists" (CLs).
Key Terminology
Before diving in, here's how Google's internal vocabulary maps to standard GitHub terms:
| Google term |
GitHub / common equivalent |
| CL (Change List) |
Pull Request (PR) |
| LGTM |
Approve / "Looks Good To Me" |
| Nit |
Minor, non-blocking comment |
| Critique / Gerrit |
GitHub PR interface |
| Readability review |
Language-specific style approval |
The One Overriding Principle
Every rule in Google's guide flows from one foundational idea:
Approve a PR once it definitely improves the overall code health of the system — even if it isn't perfect. There is no such thing as perfect code. There is only better code.
This is a deliberate counterweight to two failure modes:
The standard is not "does this code meet my ideal?" but rather "does this move the codebase forward?" The reviewer owns a stake in that outcome — they share responsibility for code health with the author.
What to Look for in Every PR
Google's guide identifies eight review dimensions. These are ordered by priority — design and functionality matter far more than style.
1. Design (highest priority)
Is the code well-designed and appropriate for the system? Does the approach fit the existing architecture?
Ask yourself: Would you have designed this differently? If so, is your way clearly better, or just different?
2. Functionality
Does the code behave as the author intended? Is the behavior actually good for users?
// Example: reviewer checks edge cases the author may have missed
public User GetUser(int userId)
{
// What happens when userId is 0 or negative?
// What if the DB returns multiple rows?
return _db.Query<User>("SELECT * FROM Users WHERE Id = @id", new { id = userId });
}
3. Complexity
Could the code be simpler? Will another developer easily understand and use it six months from now?
"Complexity is expensive. Simplicity scales."
Watch for: over-engineering, unnecessary abstractions, and clever tricks that are hard to follow.
4. Tests
Are there correct, well-designed automated tests? Do they cover the important cases, including edge cases and failure paths?
Note: reviewers do not manually test functionality — that is the author's responsibility. Reviewers evaluate whether the tests themselves are correct and sufficient.
5. Naming
Did the developer choose clear names for variables, classes, methods, and files?
// Bad naming
public List<Dictionary<string, object>> Proc(List<Dictionary<string, object>> d, string f)
{
return d.Where(x => (int)x[f] > 0).ToList();
}
// Good naming
public List<Dictionary<string, object>> FilterPositiveEntries(
List<Dictionary<string, object>> dataset, string fieldName)
{
return dataset.Where(entry => (int)entry[fieldName] > 0).ToList();
}
Are comments clear, useful, and explaining why rather than what?
// Bad comment — explains the "what", which is already obvious from the code
// Loop through users and increment counter
foreach (var user in users)
{
counter++;
}
// Good comment — explains the "why"
// We count active users separately from total to exclude soft-deleted accounts,
// which still appear in the Users table with Status = "Deleted".
foreach (var user in users)
{
if (user.Status == UserStatus.Active)
activeCount++;
}
7. Style
Does the code follow the team's style guide? Style is the lowest priority — it should never block a PR unless it violates a written standard.
8. Documentation (lowest priority)
Are READMEs, changelogs, and API docs updated to match the change? Documentation updates must be in the same PR — not deferred to a follow-up.
How to Navigate a PR: The 3-Step Approach
Google's guide provides a concrete reading order that avoids getting lost in line-by-line details before understanding the big picture.
Step 1 — Read the description
Understand the intent. Does the PR description explain what problem this solves and why this approach was chosen?
Step 2 — Find and review the main files first
Identify the files with the most logical changes. Review those for design issues before reading anything else.
If there is a major design flaw in the core files, a large portion of the remaining code will be rewritten anyway. Catching this early saves everyone's time.
Step 3 — Review remaining files
After confirming no major design problems exist, go through the remaining files in order.
Bonus tip: Read the tests before the implementation. Tests describe what the code is supposed to do — they give you a mental model before you see the business logic.
The quality of a comment determines whether a review is productive or demoralizing. Google's guide is explicit: comment on the code, never on the developer.
| Prefix |
Meaning |
Nit: |
Minor polish — not a blocker. The author can ignore it. |
Optional: |
A suggestion worth considering, but not required for approval. |
FYI: |
Informational only. No action required. |
| (no prefix) |
A required change. Blocking feedback. Always explain why. |
Show the principle, not just the fix
Unhelpful:
Change this to use a map.
Actionable:
This loop is O(n²). Using a map here would make the lookup O(1),
which matters at the volume this function is called.
See the same pattern in payments/utils.go:47.
The better comment explains the engineering principle. The developer learns a pattern they'll apply in future PRs — not just a one-time fix. Code review is also a mentoring channel.
Flag problems, don't always prescribe solutions
It is often better to point out a problem and let the developer solve it — the author knows the code's context best.
"There's an unhandled edge case when the list is empty."
is often more useful than rewriting the code for them. The author will find a solution that fits the surrounding context better.
Give credit where it's due
Code reviews often focus only on mistakes, but Google's guide is explicit: recognizing good work explicitly reinforces best practices and balances the inevitably critical tone of corrections.
// Great use of Polly's retry policy with exponential backoff here.
// Clean and exactly what this service needed.
Review Speed: The One-Business-Day Rule
Google optimizes for team velocity, not individual velocity. Slow reviews create compounding problems: blocked developers, growing frustration, and pressure to accept lower-quality code.
The rules
First response within one business day. This is the maximum — not the target. Responding before end of day keeps the author unblocked.
Don't interrupt focused work. If you're in deep work, finish it first. Batch your review sessions.
Emergency PRs get priority. A PR that fixes a production outage, closes a security hole, or unblocks a major launch should skip the queue. Speed matters more than perfection in genuine emergencies.
The paradox of strict reviews
Counter-intuitively, consistent review standards make reviews faster over time. Developers internalize what's expected and submit higher-quality PRs, requiring fewer round trips.
Do not lower your standards to speed up a review. Approving a bad PR to avoid delay creates far more rework later.
Keep PRs Small
One of the most impactful — and most resisted — practices in Google's guide is the insistence on small PRs.
The data: 90% of code reviews at Google involve fewer than 10 files, and the median review completes in under 4 hours. The median at most other large companies is 15–24 hours. The primary difference is PR size.
Why small PRs win
Reviewed faster — Finding 5 minutes twice is easier than blocking half an hour.
Reviewed more deeply — Feedback quality degrades with volume. A reviewer's attention is finite.
Easier to roll back — A focused, single-purpose change is trivially reverted.
Fewer merge conflicts — Small PRs land fast and don't go stale while the rest of the codebase moves.
Splitting large changes
The usual objection is "but this feature requires a big change." Google's answer: split it.
# Example: a new feature requiring DB schema changes + API + tests
PR 1: Add DB migration and schema change (no business logic yet)
PR 2: Add the repository/data layer
PR 3: Add the API endpoint + integration tests
PR 4: Update documentation
Each unit is reviewable on its own merits and independently deployable.
Red flag: A PR titled "Various fixes and improvements" touching 40 files is not a PR — it's a rubber-stamp waiting to happen because no reviewer has the energy to read it properly.
How to Handle Reviewer–Author Conflicts
Disagreements are normal. Google's escalation path is clear and sequential.
Level 1 — Resolve in PR comments
Reference the Engineering Practices guide or team standards to ground the discussion in shared principles, not personal opinions. Technical facts and data overrule preferences.
Level 2 — Move to a synchronous conversation
A 10-minute call resolves in minutes what async comments drag out for days. Record the outcome as a comment on the PR so future readers have context.
Level 3 — Escalate to a technical lead or team
If consensus still can't be reached, bring in a wider audience: a team discussion, a tech lead's ruling, or an engineering manager's decision.
The hard rule: A PR should never just stall. Paralysis is worse than an imperfect decision. Never let a change sit around because the reviewer and author can't come to an agreement.
Style: The Lowest-Priority Dimension
Style is where many code reviews go wrong — reviewers spend disproportionate time on whitespace and naming conventions while missing design flaws.
The rules on style
The style guide is the only authority. Personal preferences don't override it, even from senior engineers.
Style issues not in the guide are personal preference — accept the author's choice.
If no prior style exists in the codebase, accept the author's style.
Style feedback should always be a Nit: — never a blocker on its own.
// Correct: style violation with a nit prefix
// Nit: Our convention is PascalCase for method names.
// processUserData() → ProcessUserData()
// Correct: no prior convention exists
// LGTM — no existing convention here, your choice is fine.
// Wrong: blocking a PR over personal preference
// Request changes: I prefer var over explicit types everywhere. Please change.
// ↑ Reject this. Style not in the guide = personal preference.
The PR Author's Responsibilities
The guide isn't one-sided. Authors have responsibilities too.
Author checklist before opening a PR
The PR has a clear description explaining why this change is needed, not just what was done.
The change is self-contained and as small as reasonably possible.
Tests and documentation are included in the same PR — not deferred to a follow-up.
The author has reviewed their own diff before requesting review.
The best-suited reviewers are assigned — not just whoever is most available.
No speculative functionality: only implement what is needed now, not what might be needed later.
Applying This to Your Team
You don't need to overhaul your process at once. Three changes deliver most of the improvement:
1. Adopt the comment prefixes immediately
Add Nit:, Optional:, and FYI: to your team's vocabulary. It costs nothing and eliminates a major source of review friction within the first week.
2. Set a one-business-day SLA
Agree as a team that PRs get a first response within one business day. Most complaints about "strict reviews" disappear when reviews are also fast reviews.
3. Enforce small PRs
Set a soft limit (e.g. 400 lines of non-generated code). Large PRs require a written justification in the description. This single change has the biggest impact on review quality and velocity.
Once those habits are established, add the eight-dimension review checklist to your PR template, and ensure your style guide is documented so reviewers have a shared authority instead of arguing personal preferences.
Summary
| Principle |
Practical rule |
| Improve code health |
Approve PRs that move the codebase forward, even if imperfect |
| Review order matters |
Design first, style last |
| Navigate top-down |
Description → main files → remaining files |
| Comment clearly |
Use Nit: / Optional: / FYI: prefixes |
| Move fast |
First response within one business day |
| Keep it small |
Target under 10 files; always under 400 lines |
| Resolve conflicts |
Comments → sync call → escalate. Never stall. |
| Authors own quality |
Self-review, small scope, include tests |
Further Reading
Thanks, and happy coding.
