Code Review
A second person reading a change before it lands, and the practices that make it worth the time.
Code review is the practice of having someone other than the author read a change before it is merged. Its documented benefits are defect detection and knowledge distribution, and the second is often the larger one — review is how a team stays able to work on each other's code.
What review is uniquely good at is precisely what automation cannot do: judging whether the approach is right, whether the naming will make sense to someone later, whether the change belongs where it was put, and whether the claims in the description are true. Nothing mechanical can check prose, so an unverified causal statement or a false exhaustive claim reaches production unless a reader catches it. See Plausible Mechanism and Exhaustive Claim.
What makes review effective is mostly logistical. Small changes get read; large ones get skimmed. Reviewers need the evidence where the review happens, not in a place only the author can see. And a reviewer should be cold — fresh perspective is the whole mechanism, which is why self-review reliably declares work satisfactory. See Adversarial Review.
A reviewer's own reasoning deserves the same scepticism they apply to the change. A configuration set to strict plus a clean run feels like execution, and is configuration plus an untested inference.
See also6
Hand-picked in the note itself — the neighbours worth reading next.
Pull Request
A proposal to merge a branch, carrying review, automated checks, and the discussion around it.
Version Control & Delivery13 connections
Adversarial Review
Reviewing work with an explicit mandate to refute it, from a perspective that did not produce it.
Agents & Language Models9 connections
Atomic Commit
A commit containing exactly one logical change, complete and independently sound.
Version Control & Delivery9 connections
Human in the Loop
Requiring a person's judgement at chosen points in an otherwise automated process.
Agents & Language Models9 connections
Code Comment
Prose inside source code, useful only when it records a constraint the code cannot state.
Method9 connections
Provenance
The recorded origin of a change or a claim — who made it, when, and on what evidence.
Method18 connections
Related2
Nearby in the graph rather than deliberately chosen. Looser, sometimes surprising.
Linked from15
Notes elsewhere in the wiki that reach for this one.
- Adversarial ReviewAgents & Language Models
Reviewing work with an explicit mandate to refute it, from a perspective that did not produce it.
- Atomic CommitVersion Control & Delivery
A commit containing exactly one logical change, complete and independently sound.
- Chesterton's FenceMethod
Do not remove something whose purpose you cannot explain.
- Code CommentMethod
Prose inside source code, useful only when it records a constraint the code cannot state.
- Conventional CommitsVersion Control & Delivery
A lightweight convention giving commit messages a machine-readable type and scope.
- Documentation RotMethod
Documentation that has drifted from the system it describes, and is now worse than none.
- Exhaustive ClaimMethod
A statement of the form "the last one" or "nothing else does this" — load-bearing, and only as good as the search behind it.
- Human in the LoopAgents & Language Models
Requiring a person's judgement at chosen points in an otherwise automated process.
- Linguistic RelativityMeaning & Society
The hypothesis that language shapes thought, and the evidence that has narrowed it considerably.
- NamingMethod
Choosing identifiers so the code states its own meaning without commentary.
- Plausible MechanismMethod
A causal explanation that was inferred rather than tested, and reads as more rigorous for being specific.
- ProvenanceMethod
The recorded origin of a change or a claim — who made it, when, and on what evidence.
- Pull RequestVersion Control & Delivery
A proposal to merge a branch, carrying review, automated checks, and the discussion around it.
- Squash MergeVersion Control & Delivery
Collapsing a branch's commits into one before merging, trading granularity for a clean main history.
- Technical DebtMethod
The future cost of a present shortcut, metaphorically accruing interest.