Boy Scout Rule

Cleanup is the work that always moves to next quarter. New features have dates attached to them and cleanup does not, so postponing it looks faster every single week.

The same conversation repeats on a loop. Theo says the payment files have gotten out of hand and asks for two weeks to sort them out. Grace says the release comes first this quarter and they'll look at it after. Next quarter there is another release. The two weeks never arrive.

Meanwhile the code accumulates code smells — signs that nothing is broken yet but the structure has gone bad, like a single function grown to 400 lines or the same calculation copied into four files. Left alone, those turn into technical debt, the cost of postponed cleanup that you pay back later with interest.

The Boy Scout Rule is what a team does instead of waiting for those two weeks. Rather than scheduling cleanup as its own block of time, it rides along with work that is already happening. The name comes from the camping instruction to leave the campground cleaner than you found it.

Inside a file you already opened for some other reason, in the same change you are already making, you add one piece of cleanup small enough for a reviewer to check in a couple of minutes. Three conditions have to hold at once for it to be the rule rather than something else.

1. Scope stays inside the file you already opened. If you opened a file to fix a notification bug, the cleanup lives in that file too. Once you start opening neighboring files that were working fine, nobody can tell what the original task was anymore.
2. Size stays under the size of the original task. A pull request that changes 300 lines on the way to a 10-line fix is not the rule being followed. The fix and the cleanup are tangled together in one submitted change, and the reviewer cannot separate them.
3. Behavior stays identical. Nothing on screen may differ afterward, which confines the cleanup to what counts as refactoring — changing structure without changing what the software does.

In practice the things that fit are small and specific. Renaming a variable whose name no longer matches what it holds. Pulling a long conditional that needed a comment into a function with a name. Collecting a constant that was copied into four places into one place, which is the don't repeat yourself (DRY) principle. Deleting a function that nothing calls anymore. Each of these takes ten to thirty minutes.

Whether behavior really stayed identical is not something eyes can confirm. That makes the rule safe only where unit tests already exist — automated checks that exercise one function or module in isolation, so if the cleanup breaks something it shows up in red before the change is merged. In an area with no tests, stick to changes that are easy to reverse, like renaming.

The place it gets named out loud most often is code review, the step where a colleague reads a change before it is merged. A reviewer spots cleanup unrelated to the stated task and asks why it is there, or goes the other way and suggests that an obvious problem be fixed while the author is already in the file.

It also tends to appear as a single line in a team's contribution guide, and as something new engineers hear during their first week. Teams that never get dedicated time for cleanup reach for it first, so the smaller the team and the harder the shipping pressure, the more weight this one rule carries.

It does not overlap with what tools handle. A linter automatically catches defined violations — an unused variable, a missing error case — but it cannot judge whether a name still describes what a function does, or whether three scattered conditionals belong together as one. What only becomes visible to a person who has the file open is exactly what this rule covers.

The limit follows from that. A file nobody opens never improves. Any area untouched for six months is out of reach of the rule and needs real scheduled time instead.

"Not strictly in scope for this PR, but I fixed the variable names while I was in there — Boy Scout Rule."

The author cleaned up one small thing that was unrelated to the task, because the file was already open.

"Let's not open a separate cleanup ticket. Boy Scout Rule it."

A proposal to handle the mess through normal work rather than booking dedicated time for it.

"I'm fine with the Boy Scout Rule, but this is too much at once. I can't review it."

The cleanup outgrew the original task, so the reviewer wants the change split in two.

At Pagedeck it plays out like this. Theo opens a file to fix a bug where notification settings fail to save, and notices the same conditional copied in three places. The bug itself takes 12 lines. He spends another 20 minutes pulling the conditional into one function, and writes a line in the change description saying the fix also includes cleanup of a duplicated condition.

The reviewer uses that line to tell where the fix ends and the cleanup begins. Mia checks only whether the schedule is affected, hears the number 20 minutes, and asks nothing further. Those 20 minutes landing a few times a week are how the team stays afloat without ever getting a cleanup sprint.

The most common reading treats the rule as permission to clean up anything. It tells you to leave things better without saying how much better, so that reading comes naturally. But half the rule is the size limit. Restructure an entire file on the way to fixing one bug and the reviewer has to read 300 lines from scratch, and still cannot confirm whether the fix buried inside them is correct. After a few changes like that, teams end up banning the practice outright.

The other mistake is expecting the rule to pay off technical debt on its own. Every visit makes something slightly better, so it looks like the whole codebase improves given enough time. What actually improves is only the part people touch often. The oldest and most frightening areas are the ones nobody opens, so they stay exactly as they are. Miss that and the rule starts working against the case for real cleanup time — the discussion closes with the claim that debt is being handled because everyone follows the rule.