Leave it Better Than You Found it
Boy Scout, sharper.
Tidy the line that was touched. Cleanups belong in their own commit, not folded into a feature PR; the file already open for the bug fix is the file that gets tidied on the way past. The compounding effect of small, opportunistic cleanups is the corrective for software entropy.
Opinion
The compound interest on small cleanups is the difference between a codebase you can ship in and one you can't. The team that tidies one variable per commit ends a year with names that read like English; the team that defers tidying ends a year with the same code plus a year of accreted opacity. Martin's point in Clean Code is the same point, made from the opposite direction: the codebase is always either cleaner or dirtier than it was yesterday; the engineer chooses which.1Clean Code: A Handbook of Agile Software Craftsmanship (Prentice Hall, 2008), ch.1 page 14. The canonical formulation: always check in a module cleaner than when you checked it out. Re-published as Essay 8 of 97 Things Every Programmer Should Know (O’Reilly, 2010).
The bit I want to plant a flag on is the second sentence of the sub-line: cleanups travel in their own commit, not folded into the feature PR. Beck's Tidy First? is the modern reconciliation of the rule with the PR-discipline of P7 Short-Lived Branches.3Tidy First? A Personal Exercise in Empirical Software Design (O'Reilly, 2024). The modern reconciliation: tidyings and behaviour changes belong in different commits, possibly different PRs. The rule survives; the merge-conflict tax goes down. The cleanup belongs in a separate commit, ideally a separate PR, so the reviewer can read the structural change and the behaviour change without one obscuring the other. The rule survives. The diff hygiene survives. Both belong.
Sandi Metz's “Wrong Abstraction” is the qualifier inside the row: not all messy code is worth tidying.4“The Wrong Abstraction” (sandimetz.com, 2016). The qualifier inside the row: not all messy code is worth fixing. Code that doesn't change doesn't cost; the entropy that matters is the entropy in the files you are already in. Code that does not change does not cost; the entropy that matters is the entropy in the files already being edited. Treat the rule as opportunistic, not compulsive: the file opened to fix the bug is the file tidied on the way past; the file that stayed closed is the file Metz says to leave alone.
Copy a note and link
Grab this short comment and drop it into a PR comment or an LLM chat to prompt the right change.
Tidy the line you touched. Don't smuggle a refactor into a feature PR; do tidy the thing you came to fix. Cleanup goes in a separate commit (Beck's Tidy First); behaviour change in another. Don't refactor what you can't test, and don't let the cleanup turn into a yak shave. /tenet/leave-it-better/P6
AI eyes only
Rule: tidy what you touched, no further. Behaviour changes and tidies travel in separate commits.
Reject: refactoring files unrelated to the requested change. Reject: bundling forty unrelated edits into the behaviour-change PR. Reject: declining to fix a small mess in the file you are already editing.
Generate: make the requested behaviour change first; then in a separate commit, fix the adjacent rough edges in the same file. Each tidy is the minimum to remove a friction the next reader will feel.
Diagnostic: a reviewer should distinguish behaviour change from tidy in five seconds. If the diff mixes them, split.
Why?
- Compounding works. One small cleanup per commit ends a year with names that read like English; deferring ends a year with the same code plus a year of accreted opacity.
- The cost is incidental. The unit is small — rename one variable, split one function — and the trigger is incidental: tidy only the file you opened to change.
- Beck's Tidy First? is the modern reconciliation: tidy in a separate commit, separate PR if large. The rule survives; the merge-conflict tax goes down.
- Pair with P1 Test-First Development. A green suite is a refactoring licence; opportunistic cleanups stop being a leap of faith.
- The diff stays clean. The reviewer reads the tidy diff in two minutes, the feature diff in two minutes; merge conflicts don't compound across feature and structural changes.
- Hunt and Thomas's “broken windows” framing in reverse: every cleaned window deters the next break. The codebase signal that says “we keep this clean” is what stops the next entropy increment.
- No cleanup sprints. The team that tidies as it goes never has to schedule the dedicated refactor week; the dedicated refactor week is the sign that the rule was skipped for a year.
Origins
The phrase belongs to Robert Baden-Powell, founder of the Scout Movement, whose 1941 farewell message asked Scouts to “try and leave this world a little better than you found it.” The campsite version — leave it cleaner than you found it — softened over the next half-century into the Scouting tradition every modern engineer who hears the term has half-met somewhere.
The software adaptation belongs to Robert C. Martin. Clean Code: A Handbook of Agile Software Craftsmanship (Prentice Hall, 2008) ch.1 page 14 has the canonical formulation: always check in a module cleaner than when you checked it out.1Clean Code: A Handbook of Agile Software Craftsmanship (Prentice Hall, 2008), ch.1 page 14. The canonical formulation: always check in a module cleaner than when you checked it out. Re-published as Essay 8 of 97 Things Every Programmer Should Know (O’Reilly, 2010). Martin re-published a one-page version as Essay 8 of 97 Things Every Programmer Should Know (O'Reilly, 2010), which is the link most engineers actually read.
The deeper intellectual root is Hunt and Thomas's “broken windows” ( The Pragmatic Programmer, 1999, Topic 3 “Software Entropy”).2The Pragmatic Programmer (Addison-Wesley, 1999), Topic 3 “Software Entropy”; tip 5 “Don't Live with Broken Windows”. The prohibition direction: don't leave broken windows. Martin's rule turns the prohibition into action. The framing is from the prohibition direction: don't live with broken windows. Martin's rule turns that prohibition into action: fix one on your way past. The two pieces fit together as one discipline.
Kent Beck's 2024 Tidy First? is the modern reconciliation.3Tidy First? A Personal Exercise in Empirical Software Design (O'Reilly, 2024). The modern reconciliation: tidyings and behaviour changes belong in different commits, possibly different PRs. The rule survives; the merge-conflict tax goes down. Beck's reply to the diff-hygiene critique: tidyings and behaviour changes belong in different commits, possibly different PRs. The rule survives; the merge-conflict tax goes down. Pair this with P7 Short-Lived Branches with AI+Human Review and the practice is operationalised: one PR, one behavioural change, plus a separate PR per structural tidy.
Sandi Metz's “Wrong Abstraction” (2016) is the qualifier inside the row.4“The Wrong Abstraction” (sandimetz.com, 2016). The qualifier inside the row: not all messy code is worth fixing. Code that doesn't change doesn't cost; the entropy that matters is the entropy in the files you are already in. Not all messy code is worth fixing. Code that doesn't change doesn't cost; the entropy that matters is the entropy in the files you are already in. Metz's pragmatism is the corrective to compulsive cleanup; treat the rule as opportunistic, not mandatory.
Quotes
Always check in a module cleaner than when you checked it out. The Boy Scouts of America have a simple rule that we can apply to our profession: leave the campground cleaner than you found it.
Don't leave broken windows (bad designs, wrong decisions, or poor code) unrepaired. Fix each one as soon as it is discovered.
Tidyings are a kind of refactoring, but they're cute and small. Behaviour changes are the things you get paid for. The trick is to keep them apart.
Prefer duplication over the wrong abstraction. The cure is to dig out the bad abstraction and replace it with duplication, then wait for the new abstraction to emerge.
Evidence
Twenty external sources, ranked by author authority. The first five are the canon; expand to see the rest, including the qualifiers and the named opposers. Each links out to its primary source.
- 01Clean Code, ch.1SupportsThe canonical formulation: always check in a module cleaner than when you checked it out. Cites Baden-Powell as the source.
- 02One-page version of the Clean Code rule. The link most engineers actually read; CC-BY mirror in circulation.
- 03The prohibition direction: don't live with broken windows. The intellectual root that Martin's rule turns into action.
- 04The modern reconciliation. Tidyings and behaviour changes belong in different commits; the rule survives, the merge-conflict tax goes down.
- 05The vocabulary the rule operates in. Each refactoring (Extract Function, Rename Variable, Inline) is a specific tidy the rule names.
Twenty sources, three stances. The supporters are Martin, Hunt & Thomas, Beck's Tidy First?, and Fowler: the cleanup canon. The qualifiers further down push the line that the rule needs nuance: not all code is worth tidying, tidy in separate commits, do not refactor without tests. The opposers argue that drive-by cleanups slow review and obscure changes; the steelman the case has to address.
Examples
// Before: new feature ships; the adjacent pyramid stays.function validateHedgehogRecord(hg: Hedgehog | null): boolean { if (hg) { if (hg.weightG >= 600) { return true; } } return false;}function recordHibernation(hg: Hedgehog, log: HibernationLog): void { if (validateHedgehogRecord(hg)) { log.entries.push({ id: hg.id, since: now }); }}
// After: same feature; three lines of guard clauses on the line we touched.function validateHedgehogRecord(hg: Hedgehog | null): boolean { if (!hg) return false; if (hg.weightG < 600) return false; return true;}function recordHibernation(hg: Hedgehog, log: HibernationLog): void { if (validateHedgehogRecord(hg)) { log.entries.push({ id: hg.id, since: now }); }}
Enforcement
Apply these rules in eslint.config.mjs. The full enforcement across every tenet lives on the implementation page.
| Rule | Tool | Catches |
|---|---|---|
| unused-imports/no-unused-imports | eslint-plugin-unused-imports | imports left after a refactor — the most common cleanup signal. Auto-fixes; the engineer never opens a fix-only PR. |
| unused-imports/no-unused-vars | eslint-plugin-unused-imports | variables declared and never used. Stops the dead-state-on-the-way-past pattern from compounding. |
| no-unreachable | ESLint core | code after return / throw — the dead-code signal the rule asks the engineer to clean. |
| no-empty | ESLint core | empty blocks left after refactor. Catches the “half-cleanup” shape; either restore behaviour or remove the block. |
| Husky pre-commit (split-commit hook) | Husky pre-commit | mixed structural-and-behavioural commits — enforces Beck's Tidy First by reading the conventional-commit type and refusing the mix. |
| Conventional Commits | Conventional Commits | the commit-type taxonomy: feat / fix for behaviour, refactor / chore for structure. The vocabulary the hook reads. |
| @typescript-eslint/no-unused-vars | typescript-eslint | unused parameters and variables in TS source. |
eslint.config.mjsconfiguration snippet
import tseslint from 'typescript-eslint';
import unusedImports from 'eslint-plugin-unused-imports';
export default tseslint.config({
files: ['**/*.{ts,tsx}'],
plugins: { 'unused-imports': unusedImports },
rules: {
'unused-imports/no-unused-imports': 'error',
'unused-imports/no-unused-vars': 'warn',
'no-unreachable': 'error',
'no-empty': ['error', { allowEmptyCatch: false }],
}
});AI rules
.cursor/rules/p6-leave-it-better.mdc---
description: Prickles P6 — Leave it Better Than You Found it
globs: "**/*.{ts,tsx,js,jsx,py,java,php}"
alwaysApply: false
---
## Prickles P6 — Leave it Better Than You Found it
Tidy the line you touched. The unit is small — rename one variable, split one function, delete one dead import. The trigger is incidental: tidy only the file you opened to change.
Tidy in a separate commit. Beck's Tidy First rule: structural change and behaviour change belong in different commits, possibly different PRs.
Don't refactor what you can't test. A green suite is a refactoring licence; without one, the cleanup is walking a tightrope without a net.
Don't let the cleanup grow into a yak shave. Fowler's “opportunistic refactoring” warning: every cleanup reveals another. Use good judgment on when to stop.Repo layout, CI, and ESLint wiring for these paths live on /implementation — not repeated on every tenet.
Counter-argument
The strongest steelman is the diff-hygiene critique. Linus Torvalds' kernel CONTRIBUTING docs and Google's engineering practices both warn against folding cleanups into feature PRs.5Engineering Practices documentation, “The Code Reviewer's Guide”. Warns against smuggling cleanups into feature PRs: the reviewer can't tell behaviour change from cleanup; reverts become risky; merge conflicts multiply. The reviewer cannot tell behaviour change from cleanup; reverts become risky; merge conflicts multiply. Sandi Metz's “Wrong Abstraction” sharpens the point: not all messy code is worth fixing, and forced cleanups produce worse abstractions than the original mess.4“The Wrong Abstraction” (sandimetz.com, 2016). The qualifier inside the row: not all messy code is worth fixing. Code that doesn't change doesn't cost; the entropy that matters is the entropy in the files you are already in. Michael Feathers extends the warning into Working Effectively with Legacy Code: refactoring without a regression suite is “walking a tightrope without a net.”6Working Effectively with Legacy Code (Prentice Hall, 2004). The legacy-code corrective: refactoring without a regression suite is walking a tightrope without a net. The fix is to pair the rule with P1 Test-First.
Counter-argument retort
The diff-hygiene critique lands hardest when the cleanup obscures the behavioural change. Beck's Tidy First? answers the critique without abandoning the rule: tidy in a separate commit, separate PR if the cleanup is large, never in the same diff that ships the feature.3Tidy First? A Personal Exercise in Empirical Software Design (O'Reilly, 2024). The modern reconciliation: tidyings and behaviour changes belong in different commits, possibly different PRs. The rule survives; the merge-conflict tax goes down. The reviewer reads the tidy diff in two minutes (no behavioural change, just structure); the feature diff in two minutes (no structural change, just behaviour); both PRs land cleanly.
Metz's “Wrong Abstraction” is the second corrective. The compounding effect of small cleanups is real; the compounding effect of bad abstractions imposed in cleanup is worse. Apply the rule to names, splits, comment removals, dead-code deletions; do not “extract a function” or “introduce an abstraction” opportunistically. Pair this with A2 Three-Tier Hoisting and the rule of three: duplication earns its abstraction; opportunistic abstraction is debt.
Feathers' legacy-code point is the third: don't refactor what you can't test.6Working Effectively with Legacy Code (Prentice Hall, 2004). The legacy-code corrective: refactoring without a regression suite is walking a tightrope without a net. The fix is to pair the rule with P1 Test-First. The cleanup that breaks the production system is worse than the entropy it was trying to fix. The fix is not to skip cleanups; it is to pair the rule with P1 Test-First Development. A green suite is a refactoring licence; without one, the Boy Scout walks the tightrope without a net.
In production work, the row that tidies one thing per commit produces a codebase the next engineer can ship in. The row that doesn't produces a codebase the next engineer complains about and doesn't fix, on the grounds that the diff would be too large. Compounding works in both directions; the rule decides which.
Notes
- [1]Robert C. Martin — Clean Code: A Handbook of Agile Software Craftsmanship (Prentice Hall, 2008), ch.1 page 14. The canonical formulation: always check in a module cleaner than when you checked it out. Re-published as Essay 8 of 97 Things Every Programmer Should Know (O’Reilly, 2010).
- [2]Andy Hunt & Dave Thomas — The Pragmatic Programmer (Addison-Wesley, 1999), Topic 3 “Software Entropy”; tip 5 “Don't Live with Broken Windows”. The prohibition direction: don't leave broken windows. Martin's rule turns the prohibition into action.
- [3]Kent Beck — Tidy First? A Personal Exercise in Empirical Software Design (O'Reilly, 2024). The modern reconciliation: tidyings and behaviour changes belong in different commits, possibly different PRs. The rule survives; the merge-conflict tax goes down.