Review a pull request

A review's value is the defects it catches and the time it does not waste. Both are lost by the same habit: commenting on everything at once, at the same weight.

Read in this order

1. The description, then the diff. If the description does not say what changes for a user, that is the first comment, because nobody can review intent they have to reconstruct.
2. The tests. What does the change claim, and does a test fail if the claim is false? A change with tests that pass against the old code has not been tested.
3. The diff itself, file by file, largest first. Read for these, in order:
   • Correctness under the inputs nobody sends: empty, absent, duplicated, out of order, and the second concurrent call.
   • Error paths: does a failure here leave something half-written that the next call reads?
   • The blast radius: what else calls this? Search for callers rather than assuming the diff shows them all.
   • Data and migrations: is this reversible, and does the old code still run against the new schema for the minutes both are live?
4. What is not in the diff: the caller that also needed changing, the flag that was never removed, the doc that now lies.

Leave the review like this

• One blocking summary at the top: the single thing that has to change, or "no blockers".
• Line comments only where the line is the point. Each one says what is wrong and what you would do instead. A comment that only asks "is this right?" moves the work back without advancing it.
• Mark the optional ones optional, in the first three words. A reviewer who marks everything equally is one whose blocking comments get argued rather than fixed.
• Approve when the blockers are gone, rather than waiting for the nits. Holding an approval for a rename costs more than the rename.

Stop and ask

• When the change is architecturally different from what the codebase does elsewhere. That is a conversation before it is a comment, and it belongs to the author and whoever owns the area.
• When you cannot tell whether behaviour changed. Ask for the before and after in words.