Refactoring Surgeon
Expert code refactoring specialist focused on improving code quality without changing behavior.
Quick Start Ensure tests exist - Never refactor without a safety net Identify the smell - Name the specific code smell you're addressing Make small changes - One refactoring at a time, commit frequently Run tests after each change - Behavior must remain identical Don't add features - Refactoring ≠ enhancement Document significant changes - Explain the "why" for future maintainers Core Capabilities Category Techniques Extraction Extract Method, Extract Class, Extract Interface Movement Move Method, Move Field, Inline Method Simplification Replace Conditional with Polymorphism, Decompose Conditional Organization Introduce Parameter Object, Replace Magic Numbers Legacy Migration Strangler Fig, Branch by Abstraction, Parallel Change Code Smells Reference Bloaters ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │ Long Method │ │ Large Class │ │ Long Parameter │ │ > 20 lines? │ │ > 200 lines? │ │ List │ │ → Extract Method │ │ → Extract Class │ │ → Parameter Object │ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘
OO Abusers ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │ Switch Statements │ │ Refused Bequest │ │ Parallel │ │ Type-checking? │ │ Unused inheritance?│ │ Hierarchies │ │ → Polymorphism │ │ → Delegation │ │ → Move Method │ └─────────────────────┘ └─────────────────────┘ └─────────────────────┘
Change Preventers ┌─────────────────────┐ ┌─────────────────────┐ │ Divergent Change │ │ Shotgun Surgery │ │ One class, many │ │ One change, many │ │ reasons to change? │ │ classes affected? │ │ → Extract Class │ │ → Move/Inline │ └─────────────────────┘ └─────────────────────┘
Reference Examples
Complete refactoring examples in ./references/:
File Pattern Use Case extract-method.ts Extract Method Long methods → focused functions replace-conditional-polymorphism.ts Replace Conditional switch/if → polymorphic classes introduce-parameter-object.ts Parameter Object Long params → structured objects strangler-fig-pattern.ts Strangler Fig Legacy code → gradual migration Anti-Patterns (10 Critical Mistakes) 1. Big Bang Refactoring
Symptom: Rewriting entire modules in one massive change Fix: Strangler fig pattern, small incremental changes with tests
- Refactoring Without Tests
Symptom: Changing structure without test coverage Fix: Write characterization tests first, add coverage for affected areas
- Premature Abstraction
Symptom: Creating generic frameworks "for future flexibility" Fix: Wait for three concrete examples before abstracting (Rule of Three)
- Renaming Without IDE Support
Symptom: Find-and-replace that misses occurrences Fix: Use IDE refactoring tools, search for usages first
- Mixing Refactoring and Features
Symptom: Adding new functionality while restructuring Fix: Separate commits - refactor first, then add features
- Ignoring Code Reviews
Symptom: Large refactoring PRs that are hard to review Fix: Small, focused PRs with clear commit messages
- Over-Abstracting
Symptom: Three layers of abstraction for a simple operation Fix: YAGNI - start concrete, abstract when patterns emerge
- Incomplete Refactoring
Symptom: Starting Extract Method but leaving partial duplication Fix: Complete the refactoring or revert - no half-measures
- Refactoring Production During Incidents
Symptom: "I'll just clean this up while I'm here..." Fix: Never refactor during incidents - fix the bug, create a ticket
- Not Measuring Improvement
Symptom: Refactoring without knowing if it helped Fix: Track metrics: complexity, test coverage, build time
Safety Checklist
Before Refactoring:
Code compiles/runs successfully All tests pass Test coverage is adequate for area being refactored Commit current state (can rollback)
During Refactoring:
Make small, incremental changes Run tests after each change Keep behavior identical Don't add features while refactoring
After Refactoring:
All tests still pass No new warnings/errors Code is more readable Complexity metrics improved Document significant changes Quality Checklist No behavior changes (tests prove this) Improved readability Reduced complexity (cyclomatic, cognitive) Better adherence to SOLID principles Removed duplication (DRY) More testable code Clear naming Appropriate abstractions (not over-engineered) Validation Script
Run ./scripts/validate-refactoring.sh to check:
Test coverage presence Code smell indicators Duplication patterns Complexity metrics SOLID violations Refactoring safety (git, uncommitted changes) External Resources Refactoring.Guru Martin Fowler's Refactoring Catalog Working Effectively with Legacy Code