wesleyegberto Refactoring Patterns Framework
A disciplined approach to improving the internal structure of existing code without changing its observable behavior. Apply these named transformations when reviewing code, reducing technical debt, or preparing code for new features. Every refactoring follows the same loop: verify tests pass, apply one small structural change, verify tests still pass.
Core Principle
Refactoring is not rewriting. It is a sequence of small, behavior-preserving transformations, each backed by tests. You never change what the code does -- you change how the code is organized. The discipline of taking tiny verified steps is what makes refactoring safe. Big-bang rewrites fail because they combine structural change with behavioral change, making it impossible to know which broke things.
The foundation: Bad code is not a character flaw -- it is a natural consequence of delivering features under time pressure. Code smells are objective signals that structure has degraded. Named refactorings are the proven mechanical recipes for fixing each smell. The catalog of smells tells you where to look; the catalog of refactorings tells you what to do.
Scoring
Goal: 10/10. When reviewing or refactoring code, rate the structural quality 0-10 based on adherence to the principles below. A 10/10 means: no obvious smells remain, each function does one thing, names reveal intent, duplication is eliminated, and the test suite covers the refactored paths. Always provide the current score and specific refactorings needed to reach 10/10.
- 9-10: No visible smells. Each method does one thing, names reveal intent, duplication is eliminated, and tests cover refactored paths. Improvements would be cosmetic only.
- 7-8: Mostly clean with isolated smells (e.g., one long method, minor duplication). Core design is sound; targeted refactorings would polish without restructuring.
- 5-6: Multiple smells present across different areas. Some methods are too long, naming is inconsistent, or duplication is spreading. Refactoring is needed but risk is manageable with tests.
- 3-4: Significant structural problems: large classes, deep nesting, pervasive duplication, or poor separation of concerns. Refactoring requires a coordinated plan and tests must be established first.
- 1-2: Code works but is nearly unmaintainable. Smells are systemic -- god objects, no abstraction, tangled responsibilities. Major refactoring investment needed before safe evolution is possible.
The Refactoring Patterns Framework
Six areas of focus for systematically improving code structure:
1. Code Smells as Triggers
Core concept: Code smells are surface indicators of deeper structural problems. They are not bugs -- the code works -- but they signal that the design is making the code harder to understand, extend, or maintain. Each smell maps to one or more named refactorings that fix it.
Why it works: Without a shared vocabulary of smells, code review devolves into subjective "I don't like this." Named smells give teams objective criteria: "This is Feature Envy -- the method uses six fields from another class and only one of its own." The name points directly to the fix.
Key insights:
- Smells cluster into five families: Bloaters, Object-Orientation Abusers, Change Preventers, Dispensables, and Couplers
- Long Method is the most common smell and the gateway to most other refactorings
- Duplicate Code is the single biggest driver of maintenance cost
- A method that needs a comment to explain what it does is a smell -- extract and name the block instead
- Shotgun Surgery (one change requires edits in many classes) and Divergent Change (one class changes for many reasons) are opposites that both signal misplaced responsibilities
- Primitive Obsession -- using raw strings, ints, or arrays instead of small domain objects -- causes errors and duplication throughout the codebase
Code applications:
| Context | Pattern | Example |
|---|---|---|
| Method > 10 lines | Extract Method | Pull the loop body into calculateLineTotal() |
| Class > 200 lines | Extract Class | Move shipping logic into a ShippingCalculator |
| Switch on type code | Replace Conditional with Polymorphism | Create subclasses for each order type |
| Multiple methods use same params | Introduce Parameter Object | Group startDate, endDate into DateRange |
| Method uses another object's data | Move Method | Move calculateDiscount() to the Customer class |
| Copy-pasted logic | Extract Method + Pull Up Method | Share via a common method or base class |
See: references/smell-catalog.md
2. Composing Methods
Core concept: Most refactoring starts here. Long methods are broken into smaller, well-named pieces. Each extracted piece should do one thing and its name should say what that thing is. The goal is methods you can read like prose -- a sequence of high-level steps, each delegating to a clearly named helper.
Why it works: Short methods with intention-revealing names eliminate the need for comments, make bugs obvious (each method is small enough to verify at a glance), and enable reuse. The cognitive cost of a method call is near zero when the name tells you everything.
Key insights:
- Extract Method is the single most important refactoring -- master it first
- If you feel the urge to write a comment, extract the code block and use the comment as the method name
- Inline Method when a method body is as clear as the name -- indirection without value is noise
- Replace Temp with Query when a temporary variable holds a computed value that is used in multiple places
- Split Temporary Variable when one variable is reused for two different purposes
- Replace Method with Method Object when a method is too tangled to extract from (many local variables referencing each other)
Code applications:
| Context | Pattern | Example |
|---|---|---|
| Block with a comment | Extract Method | // check eligibility becomes isEligible() |
| Temp used once | Inline Variable | Remove const price = order.getPrice() if used once |
| Temp used in multiple places | Replace Temp with Query | Replace let discount = getDiscount() with method calls |
| Temp assigned twice for different reasons | Split Temporary Variable | Introduce perimeterWidth and perimeterHeight |
| Trivial delegating method | Inline Method | Inline moreThanFiveDeliveries() if it's return deliveries > 5 and only used once |
| Complex method with many locals | Replace Method with Method Object | Move the method into its own class where locals become fields |
See: references/composing-methods.md
3. Moving Features Between Objects
Core concept: The key decision in object-oriented design is where to put responsibilities. When a method or field is in the wrong class -- evidenced by Feature Envy, excessive coupling, or unbalanced class sizes -- move it to where it belongs.
Why it works: Well-placed responsibilities reduce coupling and increase cohesion. When a method lives in the class whose data it uses, changes to that data affect only one class. Misplaced methods create invisible dependencies that cause Shotgun Surgery.
Key insights:
- Move Method when a method uses more features of another class than its own
- Move Field when a field is used more by another class than the class it lives in
- Extract Class when one class does two things -- split along the axis of change
- Inline Class when a class does too little to justify its existence
- Hide Delegate to enforce the Law of Demeter -- a client shouldn't navigate a chain of objects
- Remove Middle Man when a class does nothing but forward calls
- The tension between Hide Delegate and Remove Middle Man is resolved case by case: hide the delegate when the chain is unstable; remove the middle man when forwarding becomes the entire class
Code applications:
| Context | Pattern | Example |
|---|---|---|
| Method envies another class | Move Method | Move calculateShipping() from Order to ShippingPolicy |
| Field used by another class constantly | Move Field | Move discountRate from Order to Customer |
| God class with 500+ lines | Extract Class | Pull Address fields and methods into their own class |
| Tiny class with one field | Inline Class | Merge PhoneNumber back into Contact if no behavior |
| Client calls a.getB().getC() | Hide Delegate | Add a.getCThroughB() so client doesn't know about C |
| Class only forwards calls | Remove Middle Man | Let client call the delegate directly |
See: references/moving-features.md
4. Organizing Data
Core concept: Raw data -- magic numbers, exposed fields, type codes represented as integers, parallel arrays -- creates subtle bugs and scatters domain knowledge. Replace primitive representations with objects that encapsulate behavior and enforce invariants.
Why it works: An int representing a currency amount has no concept of rounding rules, currency codes, or formatting. A Money object encapsulates all of that. When domain concepts are represented as first-class objects, business rules live in one place, validation happens automatically, and the type system catches errors at compile time.
Key insights:
- Replace Magic Number with Symbolic Constant as the simplest data refactoring -- it names the intent
- Replace Data Value with Object (Primitive Obsession cure) -- wrap strings and numbers in domain objects (
EmailAddress,Money,Temperature) - Encapsulate Field -- never expose a raw field; a getter/setter allows you to add validation, logging, or computation later
- Encapsulate Collection -- return an unmodifiable view; never let callers mutate your internal list
- Replace Type Code with Subclasses when the type code affects behavior; use Strategy when subclassing is impractical
- Change Value to Reference when you need identity semantics (one shared
Customerobject, not copies)
Code applications:
| Context | Pattern | Example |
|---|---|---|
if (status == 2) |
Replace Magic Number with Symbolic Constant | if (status == ORDER_SHIPPED) |
String email passed everywhere |
Replace Data Value with Object | Create EmailAddress class with validation |
| Public field | Encapsulate Field | Replace order.total with order.getTotal() |
| Getter returns mutable list | Encapsulate Collection | Return Collections.unmodifiableList(items) |
int typeCode with switch |
Replace Type Code with Subclasses | Employee -> Engineer, Manager, Salesperson |
| Duplicated customer records | Change Value to Reference | Share one Customer instance via a registry |
See: references/organizing-data.md
5. Simplifying Conditional Logic
Core concept: Complex conditionals -- deeply nested if/else trees, long switch statements, null checks scattered everywhere -- are the hardest code to read and the most likely to contain bugs. Named refactorings decompose, consolidate, and replace conditionals with clearer structures.
Why it works: A conditional with six branches and nested sub-conditions requires the reader to simulate every path mentally. Decomposing the condition into well-named methods makes each branch self-documenting. Replacing conditionals with polymorphism eliminates entire categories of "forgot to handle this case" bugs.
Key insights:
- Decompose Conditional: extract the condition, the then-branch, and the else-branch into named methods
- Consolidate Conditional Expression: merge multiple conditions that lead to the same result into one named check
- Replace Nested Conditional with Guard Clauses: handle edge cases early and return, leaving the main path unindented
- Replace Conditional with Polymorphism: the gold standard for type-based conditionals -- each type knows its own behavior
- Introduce Special Case (Null Object): eliminate
if (x == null)checks by providing an object that represents "nothing" with safe default behavior - Introduce Assertion: make assumptions explicit so they fail fast in development
Code applications:
| Context | Pattern | Example |
|---|---|---|
Long if with complex condition |
Decompose Conditional | Extract isSummer(date) and summerCharge() |
Multiple ifs return same value |
Consolidate Conditional | Combine into isDisabled() returning early |
Deeply nested if/else |
Replace with Guard Clauses | Check edge cases first, return early, flatten the main path |
| Switch on object type | Replace Conditional with Polymorphism | Each type implements its own calculatePay() |
if (customer == null) everywhere |
Introduce Special Case | Create NullCustomer with default behavior |
| Hidden assumption in code | Introduce Assertion | assert quantity > 0 at method entry |
See: references/simplifying-conditionals.md
6. Safe Refactoring Workflow
Core concept: Refactoring is only safe when wrapped in tests. The workflow is mechanical: run tests (green), apply one small transformation, run tests (green), commit. If tests go red, revert the last change -- don't debug a broken refactoring.
Why it works: Small steps make it trivial to find what went wrong (it was the last thing you did). Reverting a failed step costs seconds. Debugging a failed big-bang rewrite costs days. Frequent commits create save points you can return to.
Key insights:
- The refactoring cycle: test -> refactor -> test -> commit (repeat)
- Rule of Three: tolerate duplication once, note it twice, refactor on the third occurrence
- Preparatory refactoring: restructure code to make the feature easy before adding the feature
- Comprehension refactoring: refactor to understand code as you read it -- leave it clearer than you found it
- Litter-pickup refactoring: small improvements whenever you touch a file (Boy Scout Rule)
- When NOT to refactor: when it's easier to rewrite from scratch, when there are no tests and adding them first isn't feasible, or when the code will be deleted soon
- Refactoring and performance: refactor for clarity first, then profile and optimize the measured bottleneck -- refactored code is easier to tune because the hot path is isolated
- Branch by Abstraction and Parallel Change enable large refactorings in production systems without feature branches
Code applications:
| Context | Pattern | Example |
|---|---|---|
| About to add a feature | Preparatory Refactoring | Extract method to make new feature's insertion point clean |
| Reading unfamiliar code | Comprehension Refactoring | Rename variables and extract methods to understand intent |
| Saw a small issue while working | Litter-Pickup Refactoring | Fix the smell before moving on (Boy Scout Rule) |
| Third copy of same logic | Rule of Three | Extract the shared logic into a common method |
| Large API change in production | Branch by Abstraction | Introduce abstraction layer, migrate callers, remove old path |
| Renaming a widely-used method | Parallel Change | Add new name, deprecate old, migrate callers, remove old |
See: references/refactoring-workflow.md
Analysis Workflow
Before starting any refactoring session, follow these steps to establish a baseline and identify priorities.
Step 1: Automated Analysis — always suggest this, even when code is provided inline (user can save it to a file first):
Quick automated scan: Run
detect-smells.pyandanalyze-complexity.pyfrom the scripts directory to get an objective baseline before any manual review.
python scripts/detect-smells.py <file>
python scripts/analyze-complexity.py <file>
Step 2: Manual Review
- Walk through code systematically
- Note each smell with location and severity
- Categorize by impact (Critical/High/Medium/Low)
Step 3: Prioritization — focus on smells that:
- Block current development
- Cause bugs or confusion
- Affect most-changed code paths
Step 4: Output — Smell Report
Present to user:
- List of identified smells with locations
- Severity assessment for each
- Recommended priority order
- Request approval on priorities before proceeding
Common Mistakes
| Mistake | Why It Fails | Fix |
|---|---|---|
| Refactoring without tests | No safety net -- you can't tell if behavior changed | Write characterization tests first, then refactor |
| Big-bang rewrite instead of incremental steps | Combines structural and behavioral changes; impossible to debug | Take the smallest step possible, run tests after each |
| Refactoring and adding features at the same time | Two hats at once -- you can't verify either change in isolation | Separate the hats: refactor first (commit), then add feature (commit) |
| Renaming without updating all callers | Breaks the build or introduces dead code | Use IDE rename refactoring; search for all references |
| Extracting too many tiny methods | Creates indirection without clarity when names are poor | Each extracted method must have a name that removes the need to read the body |
| Ignoring the smell catalog | Reinventing fixes instead of applying proven recipes | Learn the named smells; each one maps to specific refactorings |
| Refactoring code that will be deleted | Wasted effort -- polish on condemned code | Ask first: is this code's lifespan long enough to justify the investment? |
| Optimizing prematurely during refactoring | Conflates clarity with performance; optimized code is often harder to read | Refactor for clarity first, then profile, then optimize the measured hot path only |
Quick Diagnostic
| Question | If No | Action |
|---|---|---|
| Do tests pass before you start? | You have no safety net | Write or fix tests first -- do not refactor without green tests |
| Can you name the smell you're fixing? | You're refactoring by instinct, not by catalog | Identify the smell from the catalog, then apply its prescribed refactoring |
| Is each method under ~10 lines? | Long Methods are likely present | Apply Extract Method to break long methods into named steps |
| Does each class have a single reason to change? | Divergent Change or Large Class smell | Apply Extract Class to separate responsibilities |
| Are there duplicated code blocks? | Duplicate Code is the most expensive smell | Extract shared logic into a common method or base class |
| Do conditionals use polymorphism where appropriate? | Switch Statements or complex if/else trees remain |
Apply Replace Conditional with Polymorphism |
| Are you committing after each refactoring step? | You risk losing work and mixing changes | Commit after every green-to-green transformation |
| Is the code easier to read after your change? | The refactoring may have added complexity | Revert and try a different approach |
Metrics Comparison
Always include a metrics comparison table (estimate if the file is not available). For exact values, run:
python scripts/analyze-complexity.py <file>
Present improvements:
- Lines of code change
- Cyclomatic complexity change
- Maintainability index change
Note: if code was provided inline, remind the user to save it to a file and run the command above to get precise metrics.
Plan Structure
Use the template at ./templates/refactoring-plan.md.
For each refactoring:
- Target: What code will change
- Smell: What problem it addresses
- Refactoring: Which technique to apply
- Steps: Detailed micro-steps
- Risks: What could go wrong
- Rollback: How to undo if needed
Reference Files
- smell-catalog.md: Comprehensive catalog of code smells organized by family -- Bloaters, Object-Orientation Abusers, Change Preventers, Dispensables, and Couplers -- with detection heuristics and fix mappings
- composing-methods.md: Extract Method, Inline Method, Extract Variable, Inline Variable, Replace Temp with Query, Split Temporary Variable, Remove Assignments to Parameters, Replace Method with Method Object -- motivation, mechanics, and examples
- moving-features.md: Move Method, Move Field, Extract Class, Inline Class, Hide Delegate, Remove Middle Man -- when and how to redistribute responsibilities between objects
- organizing-data.md: Replace Data Value with Object, Change Value to Reference, Replace Array with Object, Replace Magic Number, Encapsulate Field, Encapsulate Collection, Replace Type Code with Class/Subclasses/Strategy
- simplifying-conditionals.md: Decompose Conditional, Consolidate Conditional, Replace Nested Conditional with Guard Clauses, Replace Conditional with Polymorphism, Introduce Special Case, Introduce Assertion -- with before/after examples
- refactoring-workflow.md: The refactoring cycle, when to refactor, when NOT to refactor, refactoring and performance, Branch by Abstraction, Parallel Change
Scripts
./scripts/analyze-complexity.py: Run to analyze code complexity metrics./scripts/detect-smells.py: Run to automated smell detection