Knowledge Vault

Boy Scout Rule

3 min read

Boy Scout Rule

Leave the code cleaner than you found it.

Overview

Borrowed from the Boy Scouts of America’s principle about campsites, this rule applies continuous, incremental improvement to codebases. You don’t need to stop and do a major refactoring effort—just make small improvements every time you touch the code. Over time, these small improvements compound into significant quality gains.

The rule counteracts software entropy—the tendency for codebases to degrade over time through accumulated shortcuts, workarounds, and neglected maintenance. Without deliberate effort, every code change risks making things slightly worse. The Boy Scout Rule reverses this default.

Key Principles

Incremental Over Revolutionary

You don’t need to fix everything. Rename one unclear variable. Extract one small function. Add one missing type annotation. Small improvements are sustainable; large refactoring projects get postponed indefinitely.

Scope to Your Change

Clean up code in the vicinity of your change. If you’re modifying a function, improve that function and perhaps its immediate callers. Don’t go on a cleaning spree through unrelated files—that creates noise in version control and increases risk.

Leave a Trail

When you make an improvement, your commit message can note it: “Fixed bug X, also renamed confusing variable Y.” This helps reviewers understand the full scope of changes and sets a cultural expectation of continuous improvement.

Example

You’re adding a feature to a function and notice some issues:

// Before: You're adding discount handling
function calc(o: any): number {
  let t = 0;
  for (let i = 0; i < o.items.length; i++) {
    t = t + o.items[i].p * o.items[i].q;
  }
  return t;
}

While adding your feature, apply the Boy Scout Rule:

// After: Feature added, plus incremental cleanup
function calculateOrderTotal(order: Order): number {
  let total = 0;
 
  for (const item of order.items) {
    total += item.price * item.quantity;
  }
 
  if (order.discountPercent > 0) {
    total *= 1 - order.discountPercent / 100;
  }
 
  return total;
}

You added the discount feature (your task), but also:

  • Renamed the function from calc to calculateOrderTotal
  • Added type annotation
  • Renamed cryptic variables (t → total, p → price, etc.)
  • Used modern iteration (for...of instead of index-based)

Common Mistakes

Going too far - Cleaning up a entire module when you only needed to change one function creates risk and makes code review harder. Stay focused.

Cleaning unrelated code - If you’re fixing a bug in file A, don’t also refactor file B. Keep changes traceable and reviewable.

Ignoring the rule entirely - “I don’t have time to clean up” is how codebases rot. The rule is specifically about small changes that don’t add significant time.

Breaking things while cleaning - Improvements should be safe. Renaming a variable is safe. Changing logic “while you’re in there” without tests is risky.

Not testing after cleanup - Even simple changes like renaming can introduce errors (especially in dynamic languages). Run the tests.

References

  • Martin, R. C. (2008). Clean Code: A Handbook of Agile Software Craftsmanship. Chapter 1.
  • Hunt, A., & Thomas, D. (1999). The Pragmatic Programmer. “Don’t Live with Broken Windows.”

Graph View

Backlinks