Reading a Diff

In one sentence

A diff shows line-level additions and deletions between two versions of files; reading it well means reconstructing intent and risk from those changes.

Why it matters

Most review decisions start from a diff. If you only scan green and red lines, you miss order of operations, test coverage gaps, and claims that the change does not support.

How it works

• A unified diff lists files, then hunks. Each hunk shows context lines plus additions (+) and deletions (−).
• Start with the file list. Group generated files, tests, dependencies, and core logic.
• Read core logic before formatting and generated noise.
• Ask what behavior changed, what stayed the same, and what evidence (tests, types, docs) moved with the behavior.
• Note anything the author claims that is not visible in the diff.

Example

A small behavior change with a matching test:

--- a/src/worker.ts
+++ b/src/worker.ts
@@ -12,7 +12,7 @@
-  const timeoutMs = 5000;
+  const timeoutMs = config.workerTimeoutMs;
   await runJob({ timeoutMs });

The hunk below deletes a hard-coded timeout and adds a config read. The accompanying test file should show the new path.