Java Boy Scout

---
name: java-boy-scout
description: Applies the Boy Scout Rule to Java — leave every file a little cleaner than you found it, with small safe improvements made alongside the change you were asked for. Use when fixing, editing, debugging, or extending existing Java code, and when the user says "while you're at it", "any quick wins", "tidy this up", "improve this a bit", or you are already editing a file that has obvious small problems nearby.
---

# The Boy Scout Rule in Java

Leave the code cleaner than you found it. Not rewritten — cleaner. Small, safe, obviously-correct improvements made in passing keep a codebase from decaying, without turning every ticket into a refactor.

## The bargain

While making the change you were asked for, fix what is *in front of you*. Do not go looking.

**In scope** — the method you are editing, the ones it calls, the file you are already in.
**Out of scope** — the rest of the package, unrelated files, anything needing its own test plan.

## Safe cleanups

Each of these is verifiable by the existing test suite and reviewable in seconds:

| Cleanup | Skill |
|---|---|
| Rename a cryptic variable or method | `java-clean-names` |
| Delete a redundant or stale comment | `java-clean-comments` |
| Delete commented-out code | `java-clean-comments` |
| Extract a named method from a long one | `java-clean-functions` |
| Replace a magic number with a constant | `java-clean-general` |
| Replace nesting with a guard clause | `java-clean-functions` |
| Return `Optional` or an empty list instead of null | `java-clean-functions` |
| Add `final` to a field that never changes | `java-clean-general` |
| Replace an `instanceof` chain with a sealed switch | `java-clean-general` |
| Add the missing boundary test you noticed | `java-clean-tests` |
| Add `@Disabled` reason text | `java-clean-tests` |
| Delete a genuinely unused private method | `java-clean-functions` |

## Stop here

Leave these for their own change, and mention them instead of doing them:

- Changing behaviour, or anything a test does not cover
- Restructuring a class hierarchy or moving code between packages
- Changing a public API or method signature others call
- Upgrading a dependency or a framework annotation style
- Reformatting a whole file — it buries the real change in the diff

## Keep the diff readable

The reviewer must be able to see the actual change. If the cleanup is bigger than the fix, split it into a second commit: `fix: reject zero-amount transfers`, then `refactor: extract validateAmount`. Two small commits review faster than one mixed one.

Never mix a cleanup with a behaviour change in the same commit. When something breaks, the bisect must land on one or the other.

## When you find something too big

Say it, do not silently absorb it:

> Fixed the rounding bug. `PaymentProcessor` also builds its own `HttpClient` in three places and can't be tested without a network — worth a follow-up, too big for this change.

## Run the tests

A cleanup that breaks a test was not a cleanup. Run the suite before and after; if a rename touched a reflection-based framework binding, the compiler will not catch it.