Reviewing a pull request is a skill, and most engineers are never taught it.
We spend years learning to write code: courses, tutorials, feedback on our own pull requests. Reviewing someone else’s code we mostly pick up by watching. We see a senior engineer approve something, we leave a comment about a variable name, we click approve. Over time that becomes the method. It covers the surface of a change and very little underneath.
I have seen what that produces on teams I have worked with. Review requests collect a few reactions in the team channel and then sit. When reviews do happen, the comments are mostly about formatting and naming. Questions about what the change does to the system, or whether it should have been built this way at all, are rare.
This post is the method I use and teach: the process I follow when I review a pull request and the anti-patterns I see most often. It is written for engineers who review code and for leads who want their teams to do it well.
What a review is actually for
Ask most engineers why we review code and they will say: to catch bugs. The research says otherwise, and it has said so for a long time.
When Mika Mäntylä and Casper Lassenius classified the defects found in industrial and student code reviews, about three quarters of them did not affect visible behavior at all. They affected evolvability: how easy the code is to understand and change. A later study at Microsoft found that only around 15% of review comments pointed to a possible defect. And when Alberto Bacchelli and Christian Bird observed and surveyed developers at Microsoft, they found that finding defects was the motivation people named, but the payoff they actually got was knowledge transfer, team awareness, and better alternative solutions.
None of this means reviews do not catch bugs. They do. It means bug-catching is the smallest part of what a review produces, and a reviewer who only hunts for bugs leaves most of the value on the table.
The part that matters most for a team is knowledge. Peter Rigby and Christian Bird measured it directly across projects at Google, Microsoft, and AMD: doing peer review increased the number of distinct files a developer knew about by 66% to 150%. Review is not a tax on getting work done. It is how a team learns its own codebase.
Why engineers skip the reviews they need most
That finding explains the most common reason I see engineers avoid reviews. They open a pull request in a repository they do not know, or for a story they did not work on, and they close it again. Someone more familiar with that code should look at it. That feels responsible. It is actually a loop.
If you only review code you already know, you never come to know any new code. The repositories you are unfamiliar with stay unfamiliar, so you keep skipping them. I call this the familiarity trap.
The research cuts both ways here, which is what makes the trap so convincing. Reviewers who have previously worked on a file do leave more useful comments: in one Microsoft study, 74% of their comments were rated useful, against 60% for first-time reviewers. So the instinct is not wrong. Familiarity really does make you a better reviewer. The mistake is in the sequencing. You do not get familiar first and then start reviewing. You review, and that is how you get familiar.
Familiarity is not the prerequisite for reviewing. It is the product.
A review works at three layers, and design matters most
Once you accept that a review is more than a bug hunt, the next question is what you are supposed to be looking at. I find it helps to sort review questions into three layers, each needing more context than the last.
The code layer asks whether the change is clean, readable, and within the team’s standards. Is this nested loop necessary? Does this name say what the thing does? These are the easiest comments to make, and on many teams they are the only comments that get made.
The behavior layer asks what the code did before this change, what it does now, and whether that difference is what the pull request claims. Answering it means reading beyond the diff: the classes around the change, the callers, the response that eventually reaches a user.
The design layer asks whether this is the right change at all. Is it in the right place? Does it fit the decisions the team has made? Would a simpler approach, or something that already exists, have done the job?
Here is a small change that draws a comment at each layer. I will use it as a running example through the rest of the method.
Three lines removed, three added. Read line by line, it looks like a tidy-up, and the naming comment is the one most reviewers would leave. The comment that matters is the behavior one, and you cannot write it without knowing what the old code did for API clients.
Google’s published review guidance is direct about which layer comes first: the overall design is the most important thing to cover. That is not a new idea. When Michael Fagan formalized software inspections at IBM in 1976, design was inspected as its own step, before any code was written. The design layer is the hardest to reach, because it depends on context that only accumulates over many reviews. It is also where a review earns its keep.
Understand the behavior before you judge the code
What follows is the order I work in. It is not the only valid order, and I compress it for small changes. But each step exists for a reason, and skipping one usually shows up later.
1) Orient before you read a line
Start with the description. A good description states, in the author’s own words, what the change is trying to accomplish and how it is structured. A ticket link is a useful supplement, but it is not a substitute. A link alone cannot tell you whether this pull request covers the whole story or one slice of it, and a ticket written for project tracking rarely explains the design.
Here is the difference, using the running example:
Instead of:
PROJ-518
Prefer:
What: Customers without a region now see offers from the default
region instead of an error.
Why: Mobile sign-up does not collect a region yet (PROJ-518).
Design: The default is applied in OfferService.findOffers.
No API changes.
Out of scope: Backfilling regions for existing customers.
Verified: Unit tests for both paths; ran locally against staging data.
The second version tells you what to look for before you open a single file. It also makes a claim you can check: “No API changes.” Keep that claim in mind. It comes back in step 5.
Then size up the diff. For a small change, ask whether you can derive the intent from the code alone. For a larger one, separate the main files from the auxiliary ones. A well-scoped pull request has only a few files where the real change lives. If you cannot find them, that is already useful feedback. Check that the build passed, too. It is an annoying thing to discover forty minutes in.
Finally, take a first pass at the design before going line by line. Researchers who tracked reviewers’ eye movements found that reviewers tend to scan the whole piece of code first, and those who cut the scan short took longer to find defects. If something about the overall approach looks wrong, raise it now. A design comment that arrives last can turn the author’s careful fixes to your earlier style comments into wasted work.
2) Decide where to read
For a small, self-contained change in code you know, the review tool in your browser is fine. For anything larger, or anything in code you do not know, check out the branch and read it in your IDE. Finding usages, jumping to definitions, and opening the classes around the change are all far easier there, and those are exactly the moves the next step depends on.
3) Build the before and the after
This is the step untrained reviewers skip, and it is where most of the time goes. For each important class the pull request touches, answer three questions. What did this do before? How does the change modify that? How does the modification ripple outward, into callers, into the API response, into the data?
For the running example, my thought process runs something like this:
Before: no region -> IllegalArgumentException -> 400 to the client
After: no region -> DEFAULT_REGION offers -> 200 to the client
Effect: a client that handled the 400 (prompting the user to set a
region) now silently shows offers for the wrong region
None of that is visible in the diff. It comes from opening the controller, finding where the exception was mapped to a 400, and checking who calls the endpoint.
There is no shortcut, and this is the point I most want newer engineers to hear. If you expected to get through a large pull request in fifteen minutes, the expectation is the problem, not you. The SmartBear study of review at Cisco found that defect detection drops sharply once reviewers go faster than about 500 lines an hour. At a careful pace, a 1,000-line change is two hours of reading before you count the code outside the diff.
Two things stretch that further. The first is code smells. When code is hard to follow (deep nesting, unclear names, logic duplicated in three places), you stop trusting it, and you have to verify each piece instead of skimming. The second is criticality. When the change sits on a critical path, you slow down on purpose. Neither is a sign you are bad at reviewing. Bacchelli and Bird found that understanding the change is the central challenge of code review, and that the tools do little to help with it. You are not slow. This is the work.
4) Comment as you go, and say that you are
Leave comments the moment a thought forms, even before you understand the whole change. A good observation is easy to lose by the time you reach the last file.
On a large pull request, tell the author that this is how you work and that more comments are coming. Otherwise they will start fixing the early ones, and some of those fixes will be undone by a design comment you have not written yet.
When something is unclear, ask, and put your current understanding in the question. It lets the author confirm or correct you in a single reply.
Instead of: “Why did you remove the exception?”
Prefer: “I read this as: a customer with no region used to get a 400, and now gets default-region offers with a 200. Is that the intent? If so, the description’s ‘no API changes’ needs updating, and clients that handled the error should know.”
It also helps to label how much each comment matters. Conventional Comments is a lightweight scheme for this (issue, suggestion, question, nitpick, each marked blocking or not), and Google’s guidance asks reviewers to prefix optional comments with “Nit:” so the author knows what they can skip. The labels in the example above follow that pattern.
5) Check the intent against the evidence
Now compare what the change does with what the description says it does. In the running example, the description said “No API changes,” and step 3 showed a 400 becoming a 200. Either the description is wrong or the code is. Look for changes that fall outside the stated scope, too, and check that removals are explained as carefully as additions.
Then read the tests, and ask a specific question: do these tests actually verify the intent you just worked out? Consider this one:
@Test
void returnsOffersWhenRegionMissing() {
Customer customer = new Customer(null);
assertThat(service.findOffers(customer)).isNotEmpty();
}
It passes, and it proves very little. It confirms that something comes back. It does not check that the offers come from the default region, and nothing anywhere tests what an API client now receives. A test that would catch the behavior change asserts on the region of the returned offers and on the response status at the controller.
I read tests last on purpose, because I want to understand the change before I judge whether it is proven. That ordering has a cost, which I come back to below.
6) Ask whether you would have built it this way
With the context you now have, step back. Is there a simpler approach? Does something already exist that does this? Does the change follow the decisions the team has made, or does it copy an older pattern the team has decided to stop using? Authors often model new code on old code without knowing the decision changed.
I once reviewed a change that added a large amount of custom logic for what should have been a modest feature. Every line was reasonable. The complexity was the tell. A simplified version of the pattern looks like this:
// What the pull request added (abridged)
public Receipt submit(Order order) throws InterruptedException {
int attempts = 0;
while (true) {
try {
return client.submit(order);
} catch (TransientException e) {
if (++attempts >= MAX_ATTEMPTS) {
throw e;
}
Thread.sleep(BASE_BACKOFF_MS * (1L << attempts));
}
}
}
Nothing in it is wrong, line by line. But retry with backoff is a solved problem, and in our case the internal framework the service already ran on provided it, tested and proven in other applications:
// What the framework already offered (Spring Retry shown for illustration)
@Retryable(value = TransientException.class, maxAttempts = 3,
backoff = @Backoff(delay = 200, multiplier = 2))
public Receipt submit(Order order) {
return client.submit(order);
}
A line-by-line review would have approved the first version. Only a design question caught it.
This is the hardest step to do well, and newer reviewers will not always be able to. That is fine. It is the step the familiarity trap keeps out of reach, and it comes with repetitions.
7) Decide, and check that you could explain it
Google’s standard for approval is useful here: approve once the change “definitely improves the overall code health,” even if it is not perfect. Perfection is not the bar. Improvement is.
Before you approve, run a quick check on yourself. Without reopening the diff, can you explain what the change does, and what has to be true for it to be correct? For the running example: it returns default-region offers when a customer has no region, and it assumes no client depends on the old error. If you can state the assumption, you can check it. If you cannot explain what the change does, you have not reviewed it yet.
Stamina is part of the method
Reviewing is concentrated work, and attention runs out. The same SmartBear study found that effectiveness drops beyond roughly 200 to 400 lines of code in a single review, and beyond 60 to 90 minutes of continuous reviewing.
Two things follow. First, timebox your sessions, not your reviews. A complex pull request can still take hours. It just should not take them in one sitting. Second, notice what the order of the method does to the tests. Because they come last, on a large change they get read when you are most tired. If a change wears you out before you reach the tests, review them in a fresh session.
I also try to ask where the fatigue is coming from. Some days I start a review already tired, and that says nothing about the code. But if I came in fresh and the pull request still drained me, it was probably too large, and I think saying so is a fair review comment.
The first review is the author’s
Everything above applies to your own pull requests first. Before you ask anyone else to review a change, you should understand it well enough to review it yourself, whether you wrote every line or an AI tool wrote most of them.
That means reviewing it the way you would review someone else’s. Read your description as if you had never seen the ticket. Walk the diff in the review tool rather than your editor, because a diff view shows you the change the way your reviewers will see it. Build the before and after. Check that your tests prove the intent rather than just exercising the code.
The most effective technique I know for this is time. Finish the work on Tuesday afternoon. Open the pull request and review it yourself on Wednesday morning, before you request reviewers. A night away is often enough to read the code as an outsider would, and the issues you catch then never cost anyone else’s attention.
This is not just a courtesy. In the Cisco study, reviews where authors had annotated their own changes beforehand turned up fewer defects, and the researchers concluded it was because authors found and fixed issues while preparing, not because reviewers paid less attention. The higher the stakes, the more this matters.
Anti-patterns that look like reviews
Most of the bad reviews I have seen were not careless. They followed a pattern that felt reasonable at the time.
The credibility pass. A highly trusted author, often the tech lead, opens a pull request, and it is approved within minutes because of who wrote it. Nobody read it. The reviewers lose the chance to learn from a strong engineer’s code, the author loses the second set of eyes they asked for, and credible authors still write bugs, often in the riskiest parts of the system. Shane McIntosh and colleagues found that components with low review participation went on to have more post-release defects. Trust can decide what you review first. It cannot replace reading the code. A senior engineer’s pull request is one of the best learning opportunities a team has.
The rabbit hole. The reviewer hits something unfamiliar and starts researching it. One question leads to another, and the review never finishes. Because learning is part of the point, this one is easy to mistake for diligence. Learn enough to make the review decision, write the comment, and park the rest for later.
The AI pass. The code was generated by an AI tool, so it gets waved through. The reasoning is that the model probably got it right and reviewing slows the team down. On a throwaway prototype, a lighter review can be a fair trade. The trouble comes when the habit outlives the prototype. In one recent review I found a generated comment like this:
/**
* Feature flag that can be toggled at runtime to turn off the beta
* dashboard without a redeploy. Also read by the notification service.
*/
@Value("${features.beta-dashboard.enabled}")
private boolean betaDashboardEnabled;
The code was fine. The comment was wrong twice. In the application I was reviewing, a value injected this way was read once at startup, so changing it required a restart or a redeploy. And the second sentence describes another service entirely, which means it will quietly go stale the next time that service changes. The next reader would have trusted it.
The unreviewed dump. This is the author-side version of the AI pass: a pull request full of generated code the author has not verified, counting on review to catch the problems. Mandatory review makes it easy to fall into, because the approval step starts to feel like the safety net. Simon Willison has argued that proving the code works is the author’s job, and that handing unverified code to reviewers just moves the real work onto them. When the unreviewed dump meets the AI pass on the same pull request, nobody has verified the code at all.
Match the rigor to the stakes
Not every change deserves the same depth of review, and pretending otherwise is how teams end up with rubber stamps. The useful question is what is at risk.
For a prototype or other non-production work, a lighter pass is reasonable. The author should make sure it builds and say which parts were generated and not deeply verified. The reviewer can focus on direction rather than detail.
For production code with contained impact, the author should understand every line, describe the design in their own words, and prove the change works, through automated tests, manual testing, or both. The reviewer works through all three layers.
For high-stakes changes (shared contracts, data migrations, authentication, money, anything handling untrusted input), the author should also include evidence that the change works, such as test results or a walkthrough, and a note on what could break. The reviewer reads every line, and pulls in someone with the right expertise if they do not have it.
The same scale applies to how much you trust AI output. The higher the stakes, the less of it goes through on faith. AI can help you review, too. Once the branch is on your machine, asking a coding assistant why something is built a certain way, or whether a library already does it, is a fast way to generate leads. Treat the answers as leads. Verify them in the code before they go into a comment.
Review is a skill, not a gate
None of this works if a team treats review as a gate rather than a skill. The fix I keep coming back to is not a new checklist. It is a change in what people believe a review is for. Once engineers see review as the way they learn the system, an unfamiliar repository stops being a reason to skip a review and becomes a reason to start one.