Code review best practices for authors and reviewers

Most code review best practices come down to a few habits. Authors send small changes with a clear description, and reviewers respond within a business day, explain their comments, label the optional ones and approve once a change makes the codebase better, even if it isn't perfect.

Most of these practices come from Google's public engineering practices guide and from peer-reviewed studies of code review at Google and Microsoft. Google's guide says CL (changelist) for what GitHub calls a pull request. For the process itself, see what code review is and how it works.

The short version

Best practices for authors

Keep each change small

Google's guide to small CLs says "100 lines is usually a reasonable size for a CL, and 1000 lines is usually too large." It counts files too: "A 200-line change in one file might be okay, but spread across 50 files it would usually be too large." Reviewers there can reject a change for its size alone.

According to the same guide, small changes are reviewed more quickly and more thoroughly, are less likely to introduce bugs, and are simpler to roll back. Google's own changes follow this. In a 2018 study of 9 million reviewed changes at Google, Sadowski and colleagues found that the median change modified 24 lines, and about 90% touched fewer than 10 files. At Microsoft, a study of 1.5 million review comments found that the more files a change has, the lower the share of comments that are useful to its author.

How to get there:

• Make each pull request "a minimal change that addresses just one thing," in Google's words.

• Put refactorings in their own pull request, separate from behavior changes.

• Keep tests in the same change as the code they test.

• Stack dependent changes. Send one for review and start the next on top of it.

Write a description that says what and why

Reviewers can't judge what they don't understand. A study of code review at Microsoft by Bacchelli and Bird found that "code and change understanding is the key aspect of code reviewing." The description is where you hand that understanding over.

Google's guide to CL descriptions asks for two parts:

• A first line that sums up what the change does, written as an order: "Delete the FizzBuzz RPC and replace it with the new system." It should make sense on its own in the commit history.

• A body that explains the problem, why this approach, any shortcomings, and context such as bug numbers, benchmark results or design docs.

"Fix bug" doesn't qualify. As the guide asks, "What bug? What did you do to fix it?" A description that does might read:

A pull request template makes this the default. Re-read the description before you merge, too. Google points out that a change can shift a lot during review.

Let linters and formatters handle style

Software Engineering at Google describes presubmits that run tests, linters and formatters automatically when a change goes out for review. That automation "allows the reviewers to focus on more important concerns than formatting."

Google's review guide also settles style arguments in advance. Its standard of code review says "the style guide is the absolute authority," and any style point the guide doesn't cover "is a matter of personal preference." In practice:

• Run the formatter and linter in CI on every pull request, and fail the check on errors.

• When the same review comment keeps coming up, turn it into a lint rule.

• Send large reformatting as its own change. Google's reviewer guide asks authors not to mix major style changes with other changes.

Answer review comments in the code

When a reviewer says they don't understand something, Google's guide to handling reviewer comments says your first response should be to "clarify the code itself." If that isn't possible, add a code comment. Explain in the review tool only as a last resort. A reply in the thread helps one reviewer, while clearer code helps everyone who reads it later.

When you disagree, explain the tradeoff instead of refusing. Google's example of a good reply names the tradeoffs behind your choice, says why you think the alternative is worse, and asks what the reviewer had in mind. And never reply in anger. The guide calls that "a serious breach of professional etiquette that will live forever in the code review tool."

Best practices for reviewers

Finding defects was the main reason Microsoft developers gave for reviewing code, but Bacchelli and Bird found that reviews were "less about defects than expected." Reviews also spread knowledge, keep the team aware of what's changing, and turn up other ways to solve the problem.

Respond within one business day

Google's guide to review speed sets the limit: "One business day is the maximum time it should take to respond to a code review request (i.e., first thing the next morning)." Slow reviews hold up the whole team, and in Google's experience, "Most complaints about the code review process are actually resolved by making the process faster."

To make this workable:

• Don't interrupt focused work. Wait for a break point, like after lunch or a meeting.

• A quick first response counts. If you can't do a full review today, say when you will, suggest someone who can respond sooner, or send broad comments on the design.

In the 2018 Google study, the median wait for first feedback was under an hour for small changes and about 5 hours for very large ones. The median for the whole review process was under 4 hours.

If review requests keep landing on the same few people, see how your best developers become your biggest bottleneck.

Comment on the code, and explain why

Google's guide to writing review comments opens with "Be kind" and "Explain your reasoning." Make comments about the code, never about the developer. Its example of a bad comment is "Why did you use threads here when there's obviously no benefit to be gained from concurrency?" The better version says the concurrency model is "adding complexity to the system without any actual performance benefit that I can see," and recommends single-threaded code instead.

A review comment might look like this:

The same guide adds:

• Point out the problem and let the author choose the fix when you can. The guide says "it is the developer's responsibility to fix a CL, not the reviewer's," and the developer is closer to the code. Give direct suggestions when they'll help more.

• Say what you like. "If you see things you like in the CL, comment on those too!"

Label nits and optional comments

Google's guide suggests labeling the severity of comments, because "without comment labels, authors may interpret all comments as mandatory." It uses Nit for minor fixes, Optional (or Consider) for ideas that aren't required, and FYI for things to think about later. With those labels, review comments might read:

Conventional Comments goes further, with labels like issue, suggestion and question, plus (blocking) and (non-blocking) decorations. Our code review glossary lists them along with nit, PTAL and other shorthand.

Don't use the nit label to soften a real problem. If something has to change before merge, say so.

Use a checklist

A checklist keeps you from reviewing only what catches your eye. Google's guide to what to look for in a code review ends with one. Make sure that:

• The code is well-designed.

• The functionality is good for the users of the code.

• UI changes are sensible and look good.

• Any parallel programming is done safely.

• The code isn't more complex than it needs to be.

• The developer isn't building things they might need in the future but don't know they need now.

• The code has appropriate unit tests, and the tests are well-designed.

• Names are clear.

• Comments are clear and useful, and mostly explain why instead of what.

• The code is documented and follows the style guides.

The guide also asks you to "review every line of code you've been asked to review," look at the context around the change, and compliment developers on what they did well. For a fuller list, see our code review checklist.

Approve when the change improves the codebase

Google's standard of code review calls this "the senior principle among all of the code review guidelines." Reviewers "should favor approving a CL once it is in a state where it definitely improves the overall code health of the system being worked on, even if the CL isn't perfect." The guide adds that there's no such thing as perfect code, only better code.

That doesn't mean approving anything. A reviewer can still turn down a feature they don't want in their system. And outside an emergency, nothing justifies a change that makes the code's health worse. When you and the author disagree, the guide's first principle applies: "Technical facts and data overrule opinions and personal preferences."

When the only comments left are minor, Google recommends LGTM with comments: approve, and trust the author to handle the rest. It saves a round trip, which matters most when you're in different time zones.

How to review AI-written code

At Google, most new code is now AI-generated. In April 2026, Google CEO Sundar Pichai wrote that "75% of all new code at Google is now AI-generated and approved by engineers, up from 50% last fall."

That code still needs a careful read. Bug Bench, our public benchmark, counts a bug when a developer upvotes a cubic review finding on AI-written code or an AI coding agent addresses it. In its current ranking, every one of the 7 ranked models has counted bugs, and their relative bug rates run from 0.65 to 1.50, where 1.00 is the average across all AI-attributed lines. The data is observational: teams choose their models, so each rate also reflects the code that model was used for.

Hold AI changes to the same size limit

An agent can write a 2,000-line change as easily as a 50-line one, but nobody reads it any faster. Ask for the same splits you'd ask of a person: one concern per pull request, refactors separate, tests included. Google's guide makes room for large changes from "an automatic refactoring tool that you trust completely," and a coding agent whose output you have to read line by line isn't that.

Ask the author what they checked

The person who opens the pull request owns the code, whoever typed it. Ask for a description that says what the agent was asked to do, what the author read, and how they tested it. Google's guide says tool-generated descriptions should follow the same advice as hand-written ones. Bitcoin Core's contributing guide goes further. If there's reasonable doubt that the author "does not fully understand the changes they are submitting themselves," or it's clear they haven't tested them on a basic level, "the pull request may be closed immediately."

Check that every package and API exists

AI models sometimes import packages that don't exist. A USENIX Security 2025 study generated 576,000 code samples with 16 popular models. On average, at least 5.2% of the packages suggested by commercial models were hallucinated, and 21.7% for open-source models. The authors describe this as a new form of package confusion attack, because anyone can publish a package under a name that models make up.

For every new dependency, confirm it's the package you expect, from the registry you expect. Then check that each function, flag and config key the code uses exists in the version you pin.

Read for the bugs that survive a quick look

AI-written code can compile, read cleanly and pass its own tests while breaking a rule your system depends on (more in why AI code fails differently). Several of the bug types Bug Bench tracks make a reasonable checklist for these reviews: logic, business rules and compliance, error handling, security and privacy, performance, type safety and build errors, configuration and dependencies, and architecture and design. Look hard at tests the agent wrote for its own code, and check that they would fail if the code were wrong.

Let an AI reviewer take the first pass

An AI code reviewer such as cubic reviews every pull request in minutes and leaves inline comments. As our AI code review guide puts it, "It takes the first pass, so the people reviewing can spend their attention on intent and design." The human approval still decides whether the change merges.

Write your code review guidelines down

If your team's code review guidelines live only in people's heads, each new reviewer learns them one comment at a time. Put them where contributors look, such as a CONTRIBUTING.md file or a review guide in the repo. Keep them short: the change size you expect, how fast reviewers respond, which comment labels you use, and who has to approve which parts of the code. Bitcoin Core's contributing guide is a good public example, down to the exact words its reviewers use for an ACK.

FAQ

What should be checked in code review?

Google's reviewer guide lists design, functionality, complexity, tests, naming, comments, style and documentation. It also asks reviewers to read every line they're assigned and to look at the code around the change. Check that the change does what its description says, and that tests cover the new behavior.

Is code review obsolete?

No. Even where AI writes most new code, that code still goes through review: Google describes its AI-generated code as "approved by engineers." On Bug Bench, every ranked model's code had counted bugs in the latest window. What's changing is the split of work, with tools taking the mechanical first pass and people judging intent, design and risk.

What are the best skills for code review?

The first is understanding a change you didn't write. Bacchelli and Bird found understanding is "the key aspect of code reviewing." The second is knowing the codebase well enough to see what a change affects outside the diff. The third is writing comments that are clear, specific and kind, which Google's guide treats as part of the job.