# Refactoring

The disciplined improvement of existing code structure through small behavior-preserving changes that make future work safer and clearer.

- Type: practice
- Domain: Engineering & architecture
- Level: Intermediate
- Last reviewed: 2026-09-22
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/refactoring/>)

## What 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.

## Why 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.

## When 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.

## How it works

1. Identify a specific structural problem and the next change or maintenance goal it obstructs.
2. Establish fast tests or other reliable observations of the behavior that must remain unchanged.
3. Choose one small, named transformation with a clear expected result.
4. Apply the transformation and run the relevant checks immediately.
5. Commit coherent steps so failures and regressions remain easy to locate or reverse.
6. Stop when the code adequately supports current needs rather than pursuing abstract perfection.

## A 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.

## Where 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.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/refactoring/#visualization-refactoring>)

## Sources

1. [Refactoring: Improving the Design of Existing Code](<https://martinfowler.com/books/refactoring.html>) — Martin Fowler · Foundational author reference
2. [Catalog of Refactorings](<https://refactoring.com/catalog/>) — Refactoring.com · Technical pattern catalog

## Related topics

- [Test-Driven Development](<https://wiki.soroush.uk/topic/test-driven-development/>)
- [Code Review](<https://wiki.soroush.uk/topic/code-review/>)
- [Technical Debt](<https://wiki.soroush.uk/topic/technical-debt/>)
