refactoring

Related Skills

• Facing a design trade-off (DRY vs KISS)? → Use principles first to decide, then refactor
• Code is in the wrong architectural layer? → Use architecture to identify target, then refactor to move it
• Need to choose a pattern (Strategy, Factory)? → Use design-patterns first, then refactor toward it
• No tests before refactoring? → Use testing to add them first

Applicability Rubric

Condition	Pass	Fail
Existing code modification	Need to change existing code	Writing new code only
Code comprehension issues	Code hard to understand/extend	Code is clear
Feature preparation	Preparing for new functionality	Direct implementation possible
Incremental improvement	Improving quality step by step	No improvement needed

Apply when: Any condition passes

Core Principles

The Refactoring Cycle

1. Ensure tests exist (or add them)
   ↓
2. Make small change
   ↓
3. Run tests
   ↓
4. Commit if green
   ↓
5. Repeat

Golden Rules

• Never refactor and change behavior simultaneously
• Always have tests before refactoring
• Small steps, frequent commits
• If tests fail, revert immediately
• Never rewrite from scratch — a big-bang rewrite throws away years of bug fixes and domain knowledge. Instead, extract one piece at a time, test it, and ship it. If your refactoring plan requires "stop the world and replace everything," the plan is wrong — break it into smaller incremental steps.

Preserve the Semantic Contract, Not Just the Signature

Behavior is more than the type signature. A change that leaves names and types untouched can still alter what a return value promises, when effects become observable, or how failures are reported. If callers would need to reason differently about the function after the change, it is a behavior change rather than a refactor, even when the compiler is satisfied.

The semantic contract includes at least:

• Meaning of return values and out-parameters — what a given value promises happened.
• Completion timing — whether effects are visible by the time the call returns (sync vs. deferred/async).
• Observable side effects at return — which external state has been committed before returning.
• Error model — how failure is surfaced (exception, false, partial result, retried later).
• Ordering, atomicity, and delivery guarantees — all-or-nothing vs. partial, exactly-once vs. at-least-once, and similar.