Code Refactoring

Quick Reference

• •Templates: See templates.md for reporting refactoring results

Core Principle

NO REFACTORING WITHOUT TESTS FIRST

Refactor safely: tests first, incremental changes, verify behavior preserved.

When to Use

Use when encountering:

• •Code duplication (DRY violations)
• •Long functions (>50 lines)
• •High complexity (cyclomatic complexity >10, nested conditionals)
• •Placeholder functions (pass, raise NotImplementedError)
• •Magic numbers/strings
• •Deep nesting (>3 levels)
• •Large classes (>300 lines, multiple responsibilities)

Don't refactor when:

• •Code works correctly and is rarely touched
• •Refactoring would break functionality without tests
• •Time pressure requires shipping first (document debt, refactor later)

Safe Refactoring Workflow

Phase 1: Identify Target

1. •

   Detect Code Smells

   • •Long functions (>50 lines)
   • •High complexity (>10 decision points)
   • •Duplication (similar code 2+ places)
   • •Placeholder functions
   • •Magic numbers/strings
   • •Deep nesting (>3 levels)
2. •

   Understand Current Behavior

   • •Read code carefully
   • •Trace execution paths
   • •Identify dependencies
3. •

   Assess Impact

   • •What code calls this?
   • •What tests exist?
   • •What would break?

Phase 2: Write Tests (If Missing)

REQUIRED: If no tests exist:

1. •Write tests capturing current behavior
2. •Run tests to establish baseline
3. •All tests must pass before refactoring
4. •Cover: happy path, errors, edge cases, boundaries

Phase 3: Refactor Incrementally

One change at a time:

1. •Make smallest possible change (extract one method, rename one variable)
2. •Run tests after each change (must pass)
3. •Commit frequently with clear messages
4. •Verify behavior unchanged

Phase 4: Verify

1. •Run all tests (must pass)
2. •Check code quality (linter, type checker)
3. •Document changes

Refactoring Patterns

Extract Method

When: Long function, duplicated code, complex logic

Process:

1. •Identify code block to extract
2. •Create new method with descriptive name
3. •Move code, replace with method call
4. •Run tests

Extract Class

When: Class has multiple responsibilities, large class

Process:

1. •Identify cohesive group of data/behavior
2. •Create new class
3. •Move fields and methods
4. •Delegate calls
5. •Run tests

Eliminate Duplication

When: Same code appears in multiple places

Process:

1. •Identify duplicated code
2. •Extract common code to method/class
3. •Parameterize differences
4. •Replace all occurrences
5. •Run tests

Replace Placeholder

When: Function has pass, raise NotImplementedError

Process:

1. •Check if function is called (YAGNI)
2. •If unused: Remove
3. •If used: Implement functionality
4. •Write tests
5. •Run tests

Reduce Complexity

When: High cyclomatic complexity, deeply nested conditionals

Process:

1. •Extract conditions to methods with descriptive names
2. •Use early returns/guard clauses
3. •Replace nested ifs with flat structure
4. •Consider polymorphism for type-based conditionals
5. •Run tests

Extract Constant

When: Magic numbers/strings in code

Process:

1. •Identify magic number/string
2. •Create constant with descriptive name
3. •Replace all occurrences
4. •Run tests

Code Smell Quick Reference

Red Flags - STOP and Reassess

• •Refactoring without tests
• •Multiple changes in one commit
• •Tests failing after refactoring
• •Changing behavior while refactoring
• •Large refactoring without incremental steps

Integration with TDD

REQUIRED: Use testing skill before refactoring:

1. •If tests exist: Run them, ensure all pass
2. •If tests missing: Write tests using TDD workflow
3. •Refactor incrementally
4. •Run tests after each change
5. •All tests must pass before proceeding

Refactoring is part of TDD REFACTOR phase - improve code structure while keeping tests green.

Common Mistakes

The Bottom Line

Refactoring improves code without changing behavior.

Tests first. Incremental changes. Verify after each step. Preserve behavior always.