refactoring-patterns

Files (5)

• SKILL.md
• composing-methods.md · references/
• moving-features.md · references/
• organizing-data.md · references/
• refactoring-workflow.md · references/

SKILL.md (first lines)

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

## 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](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](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](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 `Customer` object, not copies)

**Code applications:**

| Context | Pattern | Example |
|---------|---------|---------|
| **`if (status == 2)`** | Replace Magic Number with Symbolic Constant | `if (status == ORDER_SHIPPED)` |

From victornovais-dev/sistema_contabilidade, MIT.

More from victornovais-dev/sistema_contabilidade