Refactoring
The disciplined improvement of existing code structure through small behavior-preserving changes that make future work safer and clearer.
Download Markdown (.md)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/refactoring/
01What it means
Refactoring changes the internal structure of software without intentionally changing its externally observable behavior. Developers apply small transformations—such as extracting a function, renaming a concept, or replacing a conditional with polymorphism—and verify behavior after each step. Refactoring is distinct from rewriting or adding a feature, even though it often occurs while preparing for or completing feature work.[1][2]
- 01Name obstructionSpecific structure blocks the next useful change
- 02Protect behaviorFast tests or reliable observations
- 03Small transformationExtract, rename, move, simplify
- 04VerifyRun relevant checks immediately
- 05Commit or reverseKeep coherent steps easy to locate
Refactoring changes internal structure without intentionally changing observable behavior; it is distinct from rewriting or adding a feature.
02Why it matters
Software design must evolve as teams learn. Refactoring reduces accidental complexity, clarifies intent, removes duplication, and creates boundaries that make the next change easier. Small, verified steps limit the diagnostic search area when something goes wrong and allow design improvement to remain part of ordinary development rather than a rare cleanup project.
03When to use it
Refactor when code is difficult to understand, duplicates knowledge, resists a needed change, or hides responsibilities. Do it before adding behavior when a clearer structure will simplify the addition, and again afterward to remove compromises. Stabilize poorly understood behavior with characterization tests before changing risky legacy code.
04How it works
- Identify a specific structural problem and the next change or maintenance goal it obstructs.
- Establish fast tests or other reliable observations of the behavior that must remain unchanged.
- Choose one small, named transformation with a clear expected result.
- Apply the transformation and run the relevant checks immediately.
- Commit coherent steps so failures and regressions remain easy to locate or reverse.
- Stop when the code adequately supports current needs rather than pursuing abstract perfection.
05A practical example
A shipping calculator contains one long conditional for destination, weight, and membership. Before adding refrigerated delivery, a developer adds characterization tests, extracts named pricing rules, and moves regional differences behind a strategy interface. Each step preserves existing totals. The new option then fits without extending the original conditional further.
06Where it breaks
Behavior-preserving changes can still alter performance, timing, logs, failure modes, or undocumented behavior. Weak tests make refactoring hazardous, while overfitted tests make it unnecessarily painful. Refactoring also has opportunity cost: polishing code unrelated to likely change can consume time without improving outcomes, and structural work should not disguise a functional rewrite.
Common mistakes
- Combining broad structural changes with new behavior in one difficult-to-review step.
- Refactoring without enough feedback to detect altered behavior.
- Treating personal style preferences as evidence that a change improves maintainability.
- Launching a large rewrite when a sequence of smaller transformations would reduce risk.
07Sources
- Refactoring: Improving the Design of Existing CodeMartin Fowler · Foundational author referenceRefactoring: Improving the Design of Existing Code
- Catalog of RefactoringsRefactoring.com · Technical pattern catalogCatalog of Refactorings