Refactoring Guide

Refactoring Principles

1. Tests first – Never refactor without test coverage
2. Small steps – One change at a time, commit frequently
3. Behavior unchanged – Refactoring ≠ feature change
4. Clear purpose – Know WHY you’re refactoring

When to Refactor

Good reasons:

• Adding a feature is harder than it should be
• Bug fixes keep touching the same code
• Code is hard to understand after a break
• Duplicate code across multiple places
• Performance requires structural change

Bad reasons:

• “I don’t like how it looks”
• “I would have done it differently”
• “Let’s modernize everything”

Code Smells & Fixes

Structural Smells

Code Duplication

Coupling Issues

Safe Refactoring Steps

Extract Function

1. Identify code to extract
2. Create new function with clear name
3. Copy code to new function
4. Replace original with function call
5. Run tests
6. Commit

Rename

1. Use IDE rename (not find-replace)
2. Update all references automatically
3. Check for string references manually
4. Run tests
5. Commit

Move Code

1. Copy to new location
2. Make old location delegate to new
3. Run tests
4. Update callers to use new location
5. Remove delegation
6. Run tests
7. Commit

Refactoring Strategies

Strangler Fig Pattern:

• Build new alongside old
• Route traffic gradually
• Remove old when unused

Branch by Abstraction:

• Introduce abstraction layer
• Implement new version behind it
• Switch implementations
• Remove abstraction if desired

Parallel Change:

• Add new, don’t modify old
• Migrate callers incrementally
• Remove old when unused

Red Flags During Refactoring

Stop and reassess if:

• Tests are failing
• Scope keeps growing
• You’re fixing bugs while refactoring
• Changes cascade unexpectedly
• You can’t explain the improvement

Output Format

When proposing refactoring:

1. Current Issues – Specific problems with current code
2. Proposed Changes – What will change and why
3. Migration Path – Step-by-step safe transition
4. Risk Assessment – What could go wrong
5. Verification – How to confirm success