Skip to content
Craft

Reading a diff as a reviewer

A diff is not a changelog. It is the author's argument, written in the only language that cannot lie: what actually changed. Review it like one.

Intermediate1 min read (computed · recorded 9)updated 2026-09-12reviewprocessdiff

by Motif Editors

revised 2026-09-12First publication in bank-3 batch 4.

Part 1 of 3 in The review craftDesign review for engineers

Key takeaways
  • Read the smallest file and the test diff first.
  • Deleted code is a behaviour change; give it more attention than additions.
  • Comment on decisions, not style — the linter already owns style.

Start at the smallest file

Reviewers read top-down and tire bottom-up, so authors put the trivial files first and the load-bearing ones last. Invert it. The one-line fix in a config file often explains the 400-line refactor behind it — read the small file first and the big one shrinks.

Then read the test diff before the source diff. Tests tell you what the author believes the code promises, and a test that changed shape is a contract renegotiation you are being asked to sign.

Three questions per hunk

What did this line do before? Why is the new version more true? What breaks that used to work? If you cannot answer the third, the author has not either — ask.

Deleted code deserves more attention than added code. Additions are intentions; deletions are behaviour changes. A delete without a test touching it is where the bugs live.

Comment on the decision, not the style

A linter owns style. Your value as a reviewer is the decisions: naming that hides a concept, a retry without a bound, a budget quietly raised. Those are the comments that survive the merge.

The studio habit

The studio log on this site records what shipped with the measurement that justified it. That is what a good review comment looks like: a claim attached to its evidence.

Practise the lesson

Theory sticks when you ship it. These original Motif assets put this guide's lesson to work — open one and copy it into your own page.