smallnest/goal-workflow/refactor

Refactor — Expert Code Restructuring

Surgical code refactoring based on Martin Fowler's <Refactoring> (2nd Edition) catalog. Improve structure, readability, and maintainability without changing external behavior. Gradual evolution, not revolution.

When to Use

This skill activates when:

• Code is hard to understand or maintain
• Functions/classes have grown too large
• Code smells are detected
• Adding features is difficult due to poor structure
• User explicitly requests refactoring, cleanup, or improvement
• User says: refactor, 重构, clean up, improve code, code smell, extract method, rename, simplify

The Golden Rules

These five rules are non-negotiable. Violating any of them turns refactoring into reckless editing.

1. Behavior is Preserved

Only how the code works changes, never what it does. If tests existed before, they must pass after. If the refactoring introduces a behavioral change, it's not refactoring — it's rewriting.

2. Small Steps

Each change should be the smallest possible transformation that compiles and passes tests. If a step breaks, you know exactly which change caused it. Refactoring is a series of tiny, safe transformations, not one big rewrite.

3. Version Control is Your Friend

Commit before starting. Commit after each successful step. This gives you infinite undo. Branch from a clean state so you can abandon the refactoring without consequences.

4. Tests are Essential

"Without tests, you're not refactoring — you're just editing." If tests don't exist for the target code, write characterization tests first. These tests capture the current behavior so you can detect regressions.

5. One Thing at a Time

Never mix refactoring with feature changes. Never refactor two unrelated things simultaneously. Each commit should contain exactly one refactoring operation.

When NOT to Refactor

Refactoring Decision Rubric

Principles guide judgment; they are not independent reasons to rewrite code. Before choosing a Fowler technique, record one decision card:

Use these four decision lenses:

SOLID is an umbrella. When evidence supports SRP, OCP, or DIP, use that specific lens and do not create a second SOLID issue. LSP and ISP may be labeled SOLID/LSP and SOLID/ISP. DRY means shared knowledge, not all similar code. Composition is preferred when inheritance creates real coupling, not by default. OCP and DIP never justify speculative layers that violate KISS or YAGNI.

Numeric thresholds in this skill—line counts, parameter counts, method counts, and nesting depth—are context-dependent candidate indicators. Confirm mixed responsibilities, cognitive cost, repeated change, duplicated knowledge, or measured runtime impact before acting.

Code Smells Catalog

Based on Fowler's taxonomy. Before refactoring, identify which smell is present.

Bloaters

Object-Orientation Abusers

Change Preventers

Dispensables

Couplers

Refactoring Techniques Catalog

Organized by category, from Fowler's catalog. Each technique includes its mechanical steps.

Composing Methods

Extract Method

Turn a code fragment into a method whose name explains its purpose.

Mechanics:

1. Create a new method named after what the fragment does (not how)
2. Copy the extracted code into the new method
3. Identify local variables: read-only become parameters, modified become return values
4. Pass parameters and handle return values
5. Replace the original fragment with a call to the new method
6. Test

Before:

void printOwing() {
    printBanner();
    // Print details
    System.out.println("name: " + _name);
    System.out.println("amount: " + getOutstanding());
}

After:

void printOwing() {
    printBanner();
    printDetails(getOutstanding());
}
 
void printDetails(double outstanding) {
    System.out.println("name: " + _name);
    System.out.println("amount: " + outstanding);
}

Inline Method

Replace a method call with its body when the method body is as clear as the name.

Mechanics:

1. Check the method is not polymorphic (no subclasses override it)
2. Find all callers
3. Replace each call with the method body
4. Delete the method definition
5. Test

Extract Variable

Put the result of an expression (or part of it) in a self-explanatory variable.

Before:

if (platform.toUpperCase().indexOf("MAC") > -1 &&
    browser.toUpperCase().indexOf("IE") > -1 &&
    wasInitialized() && resize > 0) {
    // ...
}

After:

final boolean isMacOs = platform.toUpperCase().indexOf("MAC") > -1;
final boolean isIEBrowser = browser.toUpperCase().indexOf("IE") > -1;
final boolean wasResized = resize > 0;
if (isMacOs && isIEBrowser && wasInitialized() && wasResized) {
    // ...
}

Inline Temp

Replace a temp variable with its expression when the temp is only used once and the expression is clear.

Replace Temp with Query

Extract the expression into a method. Temps that are computed once and reused are replaced with method calls.

Split Temporary Variable

A temp assigned more than once (not loop/collecting) should be split into separate variables, one per responsibility.

Remove Assignments to Parameters

Don't assign to parameters. Use a local variable instead.

Replace Method with Method Object

When a long method uses many local variables that make Extract Method hard, turn the method into its own class, with locals as fields.

Substitute Algorithm

Replace an algorithm with a clearer one.

Moving Features Between Objects

Move Method

Move a method to the class where it's used most.

Mechanics:

1. Check all features used by the method on its current class
2. Check for polymorphism (subclass/superclass methods)
3. Create the method on the target class, adapting as needed
4. Reference the target object from the source
5. Turn the source method into a delegating method, or remove it
6. Test

Move Field

Move a field to the class where it's used most.

Extract Class

When a class does the work of two, split it. Create a new class and move relevant fields and methods.

Inline Class

When a class does almost nothing, absorb it into the class that uses it most.

Hide Delegate

Create methods on the server to hide the delegate chain. manager = person.getDepartment().getManager() → manager = person.getManager().

Remove Middle Man

When a class is doing too much delegation, call the delegate directly.

Introduce Foreign Method

When a server class needs an additional method but you can't modify it, create a method on the client with the server instance as the first argument.