Refactoring Patterns

Refactoring Patterns

Code smell detection, refactoring triggers, and safe transformation patterns for improving existing code without changing behaviour.

refactor_metrics.py detects deterministic complexity signals (long functions, deep nesting, etc.). The prose sections below cover judgment-level smells that the script cannot evaluate (Feature Envy, Primitive Obsession, etc.). Run the script first to get a structural baseline; apply judgment from the prose sections to interpret findings in context.

Purpose

• Identify code smells systematically before refactoring
• Apply the right refactoring technique for each smell
• Refactor safely with tests as the safety net
• Avoid common refactoring anti-patterns that create new problems

Code Smell Catalog

Detection Examples

// SMELL: Long Parameter List (>3 params)
function createOrder(userId: string, productId: string, quantity: number, discount: number, shippingAddress: string) {}

// BETTER: Parameter Object
interface OrderRequest {
  userId: string;
  productId: string;
  quantity: number;
  discount: number;
  shippingAddress: string;
}
function createOrder(request: OrderRequest) {}

// SMELL: Primitive Obsession — email as raw string
function sendWelcome(email: string) {
  if (!email.includes('@')) throw new Error('invalid');
}

// BETTER: Value Object with self-validation
class Email {
  constructor(private readonly value: string) {
    if (!value.includes('@')) throw new Error('Invalid email');
  }
  toString() { return this.value; }
}
function sendWelcome(email: Email) {}

Refactoring Decision Rules

When to Extract

• 3+ duplications of the same code block (Rule of Three)
• Method body exceeds 20 lines
• Method has more than one clear responsibility
• Code block requires a comment to explain what it does (the comment is the method name)

When to Inline

• Abstraction adds no value (wrapper is completely transparent)
• Delegation chain exceeds 2 hops without adding logic
• Extracted method is only called from one place and the indirection obscures intent

When to Rename

• Name no longer matches current behaviour
• Domain language has evolved since the code was written
• Name uses implementation details rather than domain concepts (e.g., processArray vs applyDiscounts)

Safety Checklist

Complete all steps before beginning a refactoring session.

Before:

• Tests exist and pass at current coverage level
• Scope is bounded — know which files will change
• No behaviour changes intended (refactoring = structure only)
• Create a commit capturing the current working state (clean starting point)

During:

• Run tests after each individual refactoring step
• Refactor one smell at a time — do not chain multiple techniques in one step
• Do not fix bugs while refactoring (log them, do them separately)

After:

• All tests still pass
• No new lint warnings introduced
• Commit with message starting refactor: to distinguish from feature commits
• Update any documentation that referenced the old structure

Anti-Patterns

Related Resources

• Refactoring.Guru — full refactoring catalog
• Working Effectively with Legacy Code — Michael Feathers — adding tests to untested code
• Related skills: cc skill get testing-patterns

Invocation — Code Metrics Analyzer (L3 Script)

Before starting a refactoring session, run the metrics analyzer to get a structural baseline. Consume the script's output only — the script source never enters context.

The script supports Python files (AST-based, accurate) and JavaScript/TypeScript files (regex-based, approximate). Smells requiring contextual judgment (Feature Envy, Primitive Obsession, Data Clumps) are not detectable by the script; apply the prose catalog above to interpret findings.

Metrics detected:

Run via Bash (Python file):

python .claude/skills/code/refactoring-patterns/scripts/refactor_metrics.py path/to/module.py

Run via Bash (JS/TS file):

python .claude/skills/code/refactoring-patterns/scripts/refactor_metrics.py path/to/service.ts

Run via Bash (stdin):

cat module.py | python .claude/skills/code/refactoring-patterns/scripts/refactor_metrics.py -

Output fields (JSON):

{
  "findings": [
    {
      "metric_id": "METRIC-01",
      "name": "long_function",
      "severity": "HIGH",
      "message": "Function 'process_order' is 42 lines (threshold: 20)",
      "file": "order_service.py",
      "line": 15,
      "function": "process_order",
      "value": 42,
      "threshold": 20
    }
  ],
  "summary": {
    "total": 3,
    "high": 1,
    "medium": 1,
    "low": 1,
    "language": "python"
  }
}

What the agent does with the output:

1. Address HIGH severity findings first — these are strong refactoring candidates.
2. Review MEDIUM findings — large files and long param lists are review signals, not always blockers.
3. Use LOW findings as informational context when scoping a refactoring session.
4. Cross-reference with the prose catalog above for smells the script cannot detect.

Error handling: Invalid path → exits 1 with ERROR: message on stderr. Unsupported file extension → exits 1. Directory argument → exits 1 (pass a single file). Empty input → exits 0 with zero findings.