Simplification Pass

Simplification Pass

The goal is less code doing the same thing, verified by the same tests passing unchanged. If the tests need editing, it was a behavior change, not a simplification.

Preconditions

• Tests exist and pass before you start. Quote the run.
• The tests actually cover the behavior you are about to move. If they do not, write them first; simplification without a safety net is rewriting.
• This is its own commit, separate from any feature work.

What to look for, in order of payoff

1. Dead code. Unreferenced functions, unreachable branches, a flag that is always the same value, a parameter every caller passes identically. Delete it; git remembers.

2. Abstraction with one implementation. An interface with a single implementer, a factory that constructs one type, a strategy pattern with one strategy. It was built for a second case that never arrived.

3. Indirection that does not decide anything. A wrapper that forwards, a config value nobody sets, a layer that only renames its arguments.

4. Duplicated logic that has drifted. Two copies that are slightly different is worse than two copies that are identical, because now nobody knows which is correct. Find out which is right before merging them; the difference may be a bug fix.

5. Nesting. Guard clauses and early returns flatten most deep conditionals. Three levels is usually one extraction away from one.

6. Comments compensating for names. Rename, then delete the comment.

7. Options nobody uses. Every flag doubles the state space. Remove the ones with one real value.

Chesterton's fence

Before deleting something odd, find out why it is there. Two minutes:

• git log -S for the line, and read the commit message.
• Search for callers, including in tests, config, and other languages.
• Look for a comment or issue reference nearby.

If you find a reason, leave it and add the missing comment. If you find nothing after looking, delete it and say in the commit message that you looked.

What is not simplification

• Renaming everything to your preferred convention.
• Replacing a clear loop with a dense one-liner. Shorter is not simpler.
• Introducing a new abstraction to remove two lines of duplication. Two similar things are usually just two things.
• Changing behavior "because the old behavior looked wrong". That is a bug report, not a refactor.

Duplication is cheaper than the wrong abstraction. Wait for the third occurrence.

Process

1. Run the tests. Quote the green run.
2. Make one kind of simplification. One commit.
3. Run the tests. They must pass unchanged.
4. Repeat.
5. Report the net line change and what was removed.

Verification

• The tests are byte-for-byte unchanged and still pass.
• The diff removes more than it adds, or the addition is a name that removed a comment.
• No behavior changed. If any did, split it into its own commit with its own test.
• Anything deleted was checked against callers first.

Red flags