←   All stories

Engineering / The craft of review

The best review starts before the pull request.

Small changes. Clear intent. Better conversations. A practical guide to making your next review worth everyone’s time.

THE ANATOMY OF A BETTER REVIEW

01Intent
02Context
03Conversation

LESS FRICTION AT EVERY STEP.

A pull request is more than a bundle of changed lines. It is an invitation for another developer to understand a decision. The best reviews make that invitation easy to accept.

The work starts before you click “request review.” A few deliberate choices—about scope, description, and context—can make the difference between a useful conversation and a long, frustrating queue.

01 — Start with intent.

Before asking someone to read your code, tell them what problem you are solving. A short explanation of the why can save a long thread about the how. Give the reviewer a place to start.

A useful description answers three questions: What was happening before? What should happen now? Why did you choose this approach? You do not need to write an essay. A few clear sentences, with a link to the original issue, are usually enough.

Include the tradeoffs you considered. If a simpler approach failed, say so. Otherwise, your reviewer may spend their first twenty minutes following a path you have already ruled out.

“The smallest useful unit of review is a clear idea—not a file.”

02 — Keep it reviewable.

A focused change is easier to understand, easier to challenge, and easier to trust. Separate mechanical cleanup from behavior changes. Let one pull request tell one coherent story.

This does not mean every change must be tiny. It means each change should have a sensible boundary. Renaming a hundred references can be straightforward to review; changing five lines of authorization logic can demand much more attention.

// Make the happy path obvious.
if (!session?.isValid) return null;
return session.user;

Review your own diff first. Look for accidental formatting changes, forgotten debug statements, and comments that no longer match the code. It is a small investment that respects the attention of the next person.

If the work is genuinely large, leave a reading order. “Start with the new interface, then look at the implementation, then the callers” is a surprisingly effective way to make a complicated change approachable.

03 — Leave useful context.

Explain tradeoffs. Point out the part you are unsure about. Link to the issue that started the work. Good context does not replace a conversation; it gives the conversation a better first sentence.

Be specific about what kind of feedback you need. A draft asking for architectural direction is a different invitation from a finished change asking for a final correctness check. Making that distinction early prevents wasted effort on both sides.

Leave evidence, too. Describe how you tested the change. Include screenshots for visual work, example inputs for parsing logic, and a reproduction for a bug fix. Give the reviewer enough information to evaluate the behavior, not just the syntax.

The goal is not to eliminate every question. The goal is to spend your shared attention on the questions that matter. A better pull request gives those questions somewhere useful to begin.

GOOD IDEAS ARE BETTER SHARED.

Keep reading / Code review

A comment is a conversation, not a verdict.

Read next