Code reviews that make the next change easier

A pull request is a handoff between two people who know different amounts about the same change. The author has the whole afternoon in their head: the bug, the failed approach, the reason one branch looks odd. The reviewer opens a diff and sees the final edits.

A useful review closes that gap. It should make the behavior understandable and leave the next engineer with fewer assumptions to rediscover.

Start the description with behavior

Imagine a change to an expense-approval screen. Previously, two managers could approve the same request from separate tabs. The patch adds a version check so the second update receives a conflict and refreshes the displayed state.

That before-and-after explanation gives the reviewer a path through the diff. It is more useful than a list of filenames or “refactored approval logic.” The reviewer now knows to inspect the update condition, the conflict response, and the interface that handles it.

I would add the relevant verification next: the two-tab case, an ordinary approval, and any remaining limitation. The description should make it possible to evaluate the patch without reconstructing the conversation that produced it.

Keep one reason for the change

A formatting cleanup may be worthwhile, but including it in the approval fix makes the functional change harder to see. Separate work when it has a different reason to exist or a different reason to be rolled back.

Google's engineering guidance describes a small change as one self-contained change, rather than a universal line-count limit. That is a useful criterion for deciding where to split a pull request. Google's guidance on small changes.

A ten-line edit can still contain several unrelated decisions. A larger patch can be coherent if it carries one contract through the database, API, and interface. The reviewer needs a complete unit of behavior they can reason about.

Follow the failure through the system

For the expense example, I would inspect the call site and transaction boundary around the changed lines. A version check performed before the transaction may still allow two writers to proceed. A correct conflict response may still be confusing if the browser discards the manager's comment.

This is why reviewing context matters. Google's review guide emphasizes design, behavior, complexity, and the surrounding system, including concurrency concerns that are difficult to establish from a happy-path test alone. What to look for in a code review.

The review should connect a risk to an actual path through the code. “This might race” is a starting hypothesis. Explain which two requests can overlap and which invariant they can violate.

Give the author something actionable

Compare “Handle errors better” with this comment:

“When the second approval receives a conflict, the current handler clears the comment before refreshing the request. Preserve the draft comment so the manager can review the updated state without retyping it.”

The second comment names a trigger, describes the consequence, and suggests the intended behavior. The author can reproduce it, assess it, and choose an implementation.

Distinguish required fixes from optional improvements. A personal naming preference should not read like a correctness defect. Google's comment guidance recommends explaining the reasoning behind feedback and making severity clear. Writing useful review comments.

Put lasting explanations near the code

Some discussion belongs only in the review. Other details are needed every time someone touches the implementation. If the unusual update shape exists to make the version check atomic, that reason should be discoverable beside the code or in a meaningful test.

The final description should also describe the final patch. Remove explanations of approaches that were abandoned unless they establish a tradeoff a future maintainer will need. A review thread is useful history; it should not be the only place the current design makes sense.

For schema changes, the handoff may need a deployment sequence as well as a diff. Planning migrations around running application versions is one example where that context determines whether a correct patch can be shipped safely.

I would consider the review successful when the behavior is clearer, concrete risks have been addressed, and another engineer can make the next change with confidence about what must remain true.