irahardianto Refactoring Patterns
Catalog of safe, incremental code transformation patterns.
When to Invoke
- Executing
/refactorcommand - Technical debt remediation
- Pattern migration (e.g., callbacks → async/await)
- Code smell resolution from static analysis findings
Code Smell Taxonomy
Structural Smells
| Smell | Detection | Refactoring |
|---|---|---|
| Long method | >30 lines | Extract method |
| Large class | >300 lines or >5 responsibilities | Extract class |
| Long parameter list | >4 parameters | Introduce parameter object |
| Feature envy | Method uses another class's data more than its own | Move method |
| Data clumps | Same fields appear together repeatedly | Extract class |
| Primitive obsession | Primitives where domain types belong | Introduce value object |
Coupling Smells
| Smell | Detection | Refactoring |
|---|---|---|
| God class | One class knows/does too much | Extract classes by responsibility |
| Circular dependency | A → B → A | Introduce interface, dependency inversion |
| Inappropriate intimacy | Classes access each other's internals | Move method, extract interface |
| Shotgun surgery | One change requires touching many files | Move related code together |
Safe Transformation Techniques
1. Characterization Tests
Before refactoring, write tests that capture current behavior:
Run existing code → record outputs → assert in tests → now refactor safely
2. Strangler Fig Pattern
Gradually replace old implementation with new:
Old Code ← requests
↓ gradually route to
New Code ← requests (eventually all traffic)
Old Code ← delete
3. Branch by Abstraction
- Create abstraction (interface) over existing implementation
- Modify all clients to use abstraction
- Create new implementation behind abstraction
- Switch to new implementation
- Remove old implementation
4. Parallel Run
Run old and new implementations simultaneously, compare outputs:
Request → Old Implementation → Response (returned to user)
→ New Implementation → Response (logged, compared)
Behavior Preservation Checklist
- Tests pass before starting
- Each step is a single, atomic change
- Tests pass after each step
- Same inputs produce same outputs
- Coverage ≥ pre-refactoring level
- No new public API surface (unless intentional)
- Complexity metrics improved or unchanged
Metrics
| Metric | Tool | Target |
|---|---|---|
| Cyclomatic complexity | SonarQube, radon, gocyclo | ≤ 10 per function |
| Cognitive complexity | SonarQube | ≤ 15 per function |
| Coupling (afferent/efferent) | JDepend, NDepend | Decreasing trend |
| Duplication | SonarQube, jscpd | < 3% |
| Test coverage | lcov, coverage.py | ≥ pre-refactoring |
Related
- Code Review @.gemini/skills/code-review/SKILL.md
- Guardrails @.gemini/skills/guardrails/SKILL.md
- Testing Strategy GEMINI.md § Testing Strategy