§ 103
Small Changes
The larger a change sent for review, the less closely each line is read: defects slip through and the change waits longer for a first look.
Keep in mind
Send a change small enough to read in one sitting
What to do
Make each change one self-contained thing: about 100 lines is usually reasonable and 1000 lines usually too large, though the reviewer has the final say. Send refactoring separately from behaviour changes, and stack dependent changes instead of piling them into one. Do not split a purely mechanical change (a rename, generated code) just to hit a number, and do not cut a design so finely that the reviewer can no longer see what it does.
Why it happens
A reviewer's attention runs out. In SmartBear's study of 2,500 reviews at Cisco, reviews of under 200 lines found defects at a relatively high rate and the results trailed off considerably above that; its authors concluded that "Anything larger overwhelms reviewers and defects are not uncovered." Google's guide adds the scheduling side: "It’s easier for a reviewer to find five minutes several times to review small CLs than to set aside a 30 minute block to review one large CL." At Google the median change modifies 24 lines, and authors wait a median of under an hour for initial feedback on small changes and about 5 hours on very large ones.
When it stops applying
Per-Change Overhead: every change pays a fixed cost whatever its size (a review round trip, a CI run, the reviewer switching context), so splitting work multiplies those costs and the waits between them; when reviews are slow, a chain of tiny dependent changes can take far longer to land than one coherent change.
Source
Google, "Small CLs", Google Engineering Practices Documentation — "100 lines is usually a reasonable size for a CL, and 1000 lines is usually too large, but it’s up to the judgment of your reviewer."; SmartBear Software, "Code Review at Cisco Systems", in Best Kept Secrets of Peer Code Review (Smart Bear, 2006) — a vendor's case study of 2,500 reviews, which recommends that "LOC under review should be under 200, not to exceed 400."; Caitlin Sadowski, Emma Söderberg, Luke Church, Michal Sipko & Alberto Bacchelli, Modern Code Review: A Case Study at Google (ICSE-SEIP, 2018) — the change size and review latency figures. DORA, "Working in small batches" (dora.dev) — the counter, the fixed cost per change: "One reason work is done in large batches is because of the large fixed cost of handing off changes."
Read the sourceCite this
Hammurabi, § 103, “Small Changes.” https://kanywst.github.io/hammurabi/laws/small-changes/
BibTeX
@misc{hammurabi-small-changes,
title = {Small Changes},
author = {{Hammurabi contributors}},
note = {Hammurabi, § 103},
url = {https://kanywst.github.io/hammurabi/laws/small-changes/}
}Read in a column
- When AI writes the code Next in the column: Brandolini's Law
Related laws
- 86Approve What Improves Code HealthHolding every change to a standard of perfection makes review slow, and slow review leaves the codebase worse, not better.
- 29Boy Scout RuleCode decays because cleanup tends to be deferred to a refactor that rarely happens.
- 35Linus's LawA bug that stumps one person is often obvious to someone else looking at the same code.
- 37Little's LawIn a stable system, the average number of items inside equals arrival rate times average time spent.
- 102Automation BiasPeople working with an automated aid tend to let it stand in for their own checking: they miss what it fails to flag and follow it when it is wrong.