Boy Scout Rule — Optimize & Reconcile¶

"Always leave the campground cleaner than you found it." The rule is unconditional in spirit, but engineering is not unconditional — you have a finite budget of time, review attention, and risk tolerance per change. This file is about the economics of continuous cleanup: where a swept floor pays compound interest, where it burns money, and how to clean without destabilizing a hot path or trashing git blame. Every cleanup is an investment with a yield and a downside. We price both.

The naive reading of the Boy Scout Rule is "clean everything you touch, always." The senior reading is "clean what you touch when the expected payoff exceeds the expected cost, and pick which mess to attack so your finite cleanup budget lands where it compounds." Both the cost and the payoff are measurable. This file makes them concrete.

Table of Contents¶

1. Hotspot-driven ROI — clean where churn × complexity is highest
2. Cold, stable code — the cleanup that earns nothing
3. The risk surface of a diff — every line touched is a chance to add a bug
4. The reviewer's mental-model tax
5. Merge-conflict cost of cleanup on a long-lived branch
6. Batching cleanup vs spreading it — the review-cost curve
7. When cleanup regresses a hot path (clean abstraction over hand-tuned loop)
8. .git-blame-ignore-revs — keeping blame useful after format-only sweeps
9. Compound-interest math of technical debt — paydown vs deferred rewrite
10. Time-boxing cleanup — the 5-minute / 20% rule
11. Cleanup that invalidates a cache or warm path at runtime
12. Sequencing — refactor-then-feature vs feature-then-refactor
13. Measuring the rule worked — leading indicators of debt paydown

The decision flow¶

Scenario 1 — Hotspot-driven ROI: clean where churn × complexity is highest¶

You inherit a 180k-LOC service with debt everywhere. You have one engineer-week to spend on cleanup this quarter. Spreading it evenly across the codebase feels fair. It is also nearly worthless.

hotspot_score(file) = commits_last_180d(file) × complexity(file)

# Churn: commits per file in the last 180 days
git log --since="180 days ago" --name-only --pretty=format: \
  | grep -E '\.(go|java|py)$' | sort | uniq -c | sort -rn > churn.txt

Scenario 2 — Cold, stable code: the cleanup that earns nothing¶

A linter flags 600 violations in legacy/reporting/. The module hasn't been edited in 3 years. A teammate opens a 4000-line PR to "boy-scout" it into compliance.

Scenario 3 — The risk surface of a diff: every line touched is a chance to add a bug¶

While fixing a one-line null check, you also rename 12 variables, reorder 3 methods, and extract a helper — all "improvements." The PR is now 90 lines. It introduces a bug in the reordering that the one-line fix would never have had.

// Came to fix this:
if user != nil {            // was missing, NPE in prod
    notify(user)
}

// Got tempted to also "clean" this, in the same PR:
- func process(o *Order, c *Customer, p *Payment, opts Options) { ... }
+ func process(req ProcessRequest) { ... }   // 60-line signature refactor

Scenario 4 — The reviewer's mental-model tax¶

Your reviewer read this file last week and built a mental model of it. Your cleanup PR moves every function, renames the central type, and reflows the imports. The reviewer must rebuild their model from scratch to review a change that, semantically, does nothing.

Scenario 5 — Merge-conflict cost of cleanup on a long-lived branch¶

Three feature branches have been open for 2 weeks, all editing order_service.py. You merge a "boy-scout" cleanup to main that reformats and reorders the whole file. All three branches now face a brutal rebase.

Scenario 6 — Batching cleanup vs spreading it: the review-cost curve¶

Should you bundle 30 small cleanups into one "spring cleaning" PR, or spread them one-per-feature-PR over a month? Both have a defensible story. The right answer depends on the kind of cleanup.

Scenario 7 — When cleanup regresses a hot path¶

A reviewer asks you to replace this "ugly" hand-tuned loop with a clean, declarative stream/comprehension. The clean version is genuinely more readable. It is also 4× slower on the path that runs 2M times/sec.

// Hand-tuned, ugly, fast:
long sum = 0;
for (int i = 0; i < a.length; i++) sum += a[i];   // ~0.2 ns/elem, no boxing

// "Clean", slower on hot path:
long sum = Arrays.stream(a).asLongStream().sum();   // fine for ints…
long sum = list.stream().mapToLong(Long::longValue).sum();  // boxed: 3–5× slower, allocates

// Hot path. The "clean" closure version below may add a per-call
// indirect call the inliner can't remove; verify, don't assume.
func sumLoop(xs []int) (s int) { for _, x := range xs { s += x }; return }

func sumFold(xs []int) int {       // prettier, but check inlining + escape analysis
    return reduce(xs, 0, func(a, x int) int { return a + x })
}
// $ go test -bench=Sum -benchmem   ->  ns/op AND allocs/op for both

# Vectorized clean beats the explicit loop when data is large:
total = arr.sum()                      # numpy, C loop
total = sum(x for x in py_list)        # pure-Python, ~50–100× slower for large lists
# But a generator expression can be slower than a tight built-in on small data. timeit it.

// HOT PATH: 2M calls/s. Hand-rolled loop is 4× faster than the reduce()
// abstraction (see bench_sum_test.go, 0.21 vs 0.84 ns/op). Do not "clean up".
func sumLoop(xs []int) (s int) { for _, x := range xs { s += x }; return }

Scenario 8 — .git-blame-ignore-revs: keeping blame useful after format-only sweeps¶

You finally run a repo-wide formatter. Now git blame on every file points at your formatting commit, and git log -L for any line stops at the reformat. You've made blame archaeology — the single most useful debugging tool — nearly useless.

# 1. Make the mechanical-only commit, nothing else in it:
gofmt -w ./...           # or: black . ; isort .   |   ./gradlew spotlessApply
git commit -am "style: repo-wide gofmt, no behavior change"

# 2. Record its full SHA in the ignore-revs file:
git rev-parse HEAD >> .git-blame-ignore-revs
git commit -am "chore: ignore the formatting commit in blame"

# 3. Make it the default so everyone (and the IDE) benefits:
git config blame.ignoreRevsFile .git-blame-ignore-revs

Scenario 9 — Compound-interest math of technical debt: paydown vs deferred rewrite¶

Leadership keeps deferring cleanup: "we'll do a big rewrite next year." Meanwhile every feature in the messy module ships slower than the last. You need to make the cost of deferral concrete, because "it feels slow" loses to "ship features now."

Scenario 10 — Time-boxing cleanup: the 5-minute / 20% rule¶

A junior reports they spent a full day "boy-scouting" a file they were assigned a 1-hour bug fix in. The bug is fixed; they also rewrote half the module. The instinct was right; the budgeting was absent.

Scenario 11 — Cleanup that invalidates a cache or warm path at runtime¶

You "clean up" a service by replacing a sprawling singleton with fresh, dependency-injected instances per request. The code is clearly better. Latency p99 triples in production because the singleton was, accidentally, holding a warm cache and a pooled connection.

// "Messy" but warm: one pool, one compiled template cache, reused across requests.
class ReportService {                  // de-facto singleton
    private final ConnectionPool pool;        // warm, sized for load
    private final Map<String, Template> cache; // compiled once
}

// "Clean" DI version — a fresh instance per request:
@RequestScoped
class ReportService {                  // new pool + cold cache EVERY request
    ...                                 // p99 latency 3×; connection churn; GC pressure
}

// Clean AND warm: the amortization is now intentional and documented.
@Singleton class TemplateCache { /* compiled-once templates */ }
@Singleton class ReportConnectionPool { /* sized for load */ }

class ReportService {                  // request-scoped logic, shared warm collaborators
    ReportService(TemplateCache cache, ReportConnectionPool pool) { ... }
}

Scenario 12 — Sequencing: refactor-then-feature vs feature-then-refactor¶

You must add a feature to a tangled function. Do you clean it first (then add the feature to clean code) or add the feature first (then clean)? Kent Beck's guidance and the risk math point one way.

commit 1  refactor: extract priceLine() seam in computeTotal()  [tests unchanged, all green]
commit 2  feat: add bulk-discount via the new priceLine() seam   [new tests for the feature]

Scenario 13 — Measuring that the rule worked: leading indicators of debt paydown¶

A team adopts the Boy Scout Rule. Six months later, management asks "did it help, or did we just slow down feature delivery?" You need evidence, not vibes — and the right metrics, since the wrong ones (e.g. "lines cleaned") reward churn.

Rules of Thumb¶

• Clean where churn × complexity is highest. Hotspots carry most of the maintenance cost; cold code carries almost none. Spend your proactive cleanup budget on the top ~5% of files by commits × complexity, not evenly. (Scenario 1, 2)
• Cold + stable = leave it. A file untouched for years has ~zero future reads to repay a cleanup. Suppress the linter or delete dead code; don't reformat. (Scenario 2)
• Every changed line is a bug-injection site. Don't multiply a 1-line fix's risk by bundling 80 lines of opportunistic cleanup. Behavior changes ship small and alone. (Scenario 3)
• Respect the reviewer's mental model. Review quality collapses past ~400 LOC. Mechanical-only PRs are reviewed against a guarantee ("no behavior change"), not line-by-line — so never mix moves with edits. (Scenario 4, 6)
• Don't externalize merge-conflict cost. Time big structural sweeps for low-contention windows; prefer append-style cleanups on hot files. (Scenario 5)
• Batch by risk homogeneity. Mechanical sweeps → one repo-wide PR. Judgment renames/extractions → spread one per touched area. Never the two in one PR. (Scenario 6)
• Measure before you "clean" a hot path. A clean abstraction that regresses a proven hot path is not cleaner. Keep the fast path, wrap it, and comment the benchmark. (Scenario 7, 11)
• Always register format-only commits in .git-blame-ignore-revs — and keep those commits 100% mechanical so blame stays honest. (Scenario 8)
• Continuous small paydown beats deferred rewrite on both cost and risk in nearly every case. Bring the interest-rate table, not adjectives. (Scenario 9)
• Time-box it: ~5 minutes opportunistically, ~20% of task budget at most. Anything larger becomes a ticket scheduled by hotspot ROI — not a silent rewrite. (Scenario 10)
• Refactor first (own commit, unchanged tests green), then add the feature. If tests don't cover the behavior, add characterization tests first. (Scenario 12)
• Measure the cost of change, not the volume of cleanup. Hotspot complexity trend + DORA lead time / change-failure rate. Never reward "lines cleaned." (Scenario 13)

Related Topics¶

• README.md — the positive rules of the Boy Scout Rule and the anti-patterns to avoid.
• find-bug.md — how mixed-concern and untested cleanup PRs hide regressions.
• professional.md — making continuous cleanup part of the definition of done and the team's social contract.
• ../20-cognitive-load/README.md — the human-facing half of cleanup payoff: reducing what a reader must hold in their head.
• ../../refactoring/02-refactoring-techniques/README.md — the catalog of behavior-preserving seams used in refactor-first sequencing.
• ../../refactoring/04-large-scale-refactoring/README.md — discipline for the rare case where incremental paydown genuinely cannot converge.

Next: professional.md — making the Boy Scout Rule durable: definition of done, team norms, and the social contract of continuous improvement.