§ 86
Approve What Improves Code Health
Holding every change to a standard of perfection makes review slow, and slow review leaves the codebase worse, not better.
Keep in mind
Approve better, not perfect
What to do
Approve a change once it definitely leaves the code healthier than before, even if you would have written it differently. Prefix polish with "Nit:" so the author can skip it, and block only on what makes the code worse: outside an emergency, do not approve a change that definitely worsens overall code health.
Why it happens
There is no perfect code, only better code, so a reviewer who waits for perfect is holding out for a bar nobody reaches while the change sits. Authors respond by batching work into large changes that get reviewed less carefully, or by not touching the code that needs it, and the improvement the change carried never lands. A bar of net improvement keeps each merge moving the codebase in the right direction, while still letting the reviewer refuse anything that makes it worse.
When it stops applying
Broken Windows Theory: a reviewer who waves each small flaw through because the change is a net improvement can still leave a codebase full of tolerated flaws, each one making the next easier to accept.
Source
Google, "The Standard of Code Review", Google Engineering Practices Documentation (2019) — "favor approving a CL once it is in a state where it definitely improves the overall code health", "there is no such thing as 'perfect' code—there is only better code", and "Nit:" for optional comments.
Read the sourceCite this
Hammurabi, § 86, “Approve What Improves Code Health.” https://kanywst.github.io/hammurabi/laws/code-health-standard/
BibTeX
@misc{hammurabi-code-health-standard,
title = {Approve What Improves Code Health},
author = {{Hammurabi contributors}},
note = {Hammurabi, § 86},
url = {https://kanywst.github.io/hammurabi/laws/code-health-standard/}
}Related laws
- 29Boy Scout RuleCode decays because cleanup tends to be deferred to a refactor that rarely happens.
- 57Broken Windows TheoryVisible disorder left unrepaired can signal that standards are optional, inviting more.
- 05Law of TrivialityDiscussion goes to the parts everyone understands, not the parts that matter.
- 100Braintrust (Notes Without Authority)Feedback from people who can overrule the owner gets defended against rather than used; peers with no power to impose a fix can be candid, and the owner can afford to hear them.
- 103Small ChangesThe 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.