Skip to main content

Long-Term Code Stewardship: Boy-Scout Rule, Broken Windows, Narrative Git History

What This Concept Is​

Stewardship is the habit of leaving a codebase slightly better than you found it, across months and years. It is what separates codebases that remain pleasant to work on from codebases that quietly rot.

Three concrete habits carry most of it:

  • Boy-scout rule (Uncle Bob): check in code a little cleaner than you checked it out. Rename one variable. Delete one dead branch. Add one missing test. One small improvement per PR.
  • Broken windows (Pragmatic Programmers via Kent Beck): every tolerated small defect -- a commented-out TODO from 2022, a skipped test, a linter rule disabled "temporarily" -- lowers the bar for the next defect. Fix broken windows visibly; other engineers will stop being the ones to break the next one.
  • Narrative Git history: commits and PRs read like a story of the feature. When someone reads git log six months from now, they can follow why, not just what.

Why It Matters Here​

Design isn't just about today's code. It is about whether someone joining the team in two years will be able to work efficiently, or will spend their first month apologetically asking "why do we do it this way?" Stewardship is the invisible half of engineering judgment. It is what makes the difference between an ex-greenfield codebase that is still fun to work on after four years, and one where every change feels expensive.

Concrete Example​

Boy-scout rule in a review comment:

[nit, clarity] While you were here, calcT on line 91 is still a cryptic name from the old code. No need to expand the scope of this PR, but consider renaming to calculateTax in a follow-up (or in this PR if you feel like it).

Broken window fixed:

0f3e9ab chore: remove two-year-old commented-out billing code

One line in a PR description that would otherwise be all-feature:

Also deletes a skipped test that has been skipped since 2024 and never triaged.

Narrative Git history (using a Nygard-style ADR reference and conventional commits):

0f3e9ab refactor: extract PricingStrategy interface
b82d441 feat(promotions): add Promotion and PromotionUse models (ADR-0012)
5a7c118 feat(promotions): add /promotions/apply endpoint (no caller yet)
e2d63fa feat(checkout): call promotions service behind FEATURE_PROMOS
19ab7cf test(promotions): concurrent-redemption regression test
fa91c0b chore: remove FEATURE_PROMOS flag; promotions GA

A teammate in 2027 opens git log --oneline for the promotions feature and reads exactly the shape of the work: design decision, model, endpoint, integration, test, launch.

Compare:

a1b2c3d stuff
e4f5g6h more stuff
i7j8k9l fix
m0n1o2p PR feedback
q3r4s5t final

Same feature, same code, no history.

Common Confusion / Misconception​

"Boy-scout rule = huge cleanup PRs." It is the opposite. The rule is small, in the same PR. Massive cleanup PRs are legitimate sometimes, but they are not the rule.

"Fixing a broken window = scope creep." A deleted dead function is rarely scope creep. It is hygiene. Call it out in the PR description so nobody is surprised.

"Nobody reads commit messages." Everyone reads them, eventually: during git bisect, during git blame, during incident reviews, during onboarding. Writing for that audience is high leverage.

"Narrative history = perfect history." It does not mean no mistakes land. It means the history is honest and legible. A revert is fine; an opaque "final final" is not.

"Stewardship is senior work." It is the opposite. Stewardship is the most leveraged thing a junior can do, because every small improvement compounds and is visible to everyone who reads the diff.

"Broken windows are cosmetic." They are social. Tolerated ugliness teaches the next engineer that ugliness is tolerated. The next engineer may not have the taste or authority of the first.

How To Use It​

Habits to install:

  1. Every PR: one small improvement outside the main scope. Call it out in the description.
  2. Notice a broken window (commented-out code, disabled test, TODO older than a quarter): fix it or file a ticket; do not leave it untouched.
  3. Before pushing: git rebase -i and make the history tell the story. Squash WIP commits. Rewrite unclear subjects. Your branch, before merge.
  4. Before merge: PR description has a Summary, Risk/Rollback, How to Verify, Not in Scope -- as per the previous concept.
  5. Read other people's history occasionally. You learn more about the codebase in an hour of git log than a day of reading current files.

Explicit limits:

  • Do not rewrite shared branch history.
  • Do not rename everything in sight during a feature PR (that is the opposite of reviewable).
  • Do not fix broken windows silently; the reviewer should see them in the diff with an explanation.

Check Yourself​

  1. Why is "one small improvement per PR" sustainable when "big cleanup sprint" is not?
  2. Give a concrete broken window from a codebase you have seen. How would you have fixed it?
  3. What is the point of writing commit messages that no one reads today?

Mini Drill or Application​

Take a real branch (yours or a teammate's). Do all three:

  1. Identify one broken window and add a fix commit with a clear subject.
  2. git rebase -i the branch into a narrative 3-6 commit history.
  3. Write the PR description with explicit "Not in scope" and "Small cleanups" sections.

Read This Only If Stuck​