refactoring

Refactoring Safely

Safe restructuring, behavior-preservation, protected contracts. A refactoring changes code structure, not behavior. If behavior changes, that's a feature.

One Core Rule: Behavior Preservation

Before you refactor, decide: Am I changing code structure only, or am I changing behavior?

• Refactoring: Same inputs → same outputs. Same errors in same cases. Observable behavior identical. Only code structure changes.
• Feature: Behavior, performance, API, or error handling changes. Needs a separate PR with tests and design review.

If unsure, assume it's a feature (safer choice).

Document what must not change:

• Function/endpoint signatures
• Error modes (same exceptions in same conditions)
• Performance characteristics (if timing tests exist, they still pass)
• Database schemas (unless versioned migration)

Three-Step Safe Refactoring

1. Characterization Tests (Before Touching Code)

Write tests that capture behavior as it is today — your safeguard against accidentally changing something.

# ✅ Characterization test: lock down current behavior
def test_find_user_missing_returns_none():
    """Current behavior: missing user returns None, not exception."""
    db = TestDatabase()
    assert find_user(db, 999) is None

def test_retry_once_on_network_error():
    """Current behavior: network errors trigger exactly one retry."""
    db = MockDB(fails_on_attempt=1)
    user = find_user(db, 1)
    assert user.id == 1  # Succeeds on retry

These tests answer: "What does this code actually do right now?" — not "what should it do?" They're your canary: if they break during refactoring, you've changed behavior (either a bug or a missed feature scope).

When required (Production tier): Large refactors (5+ functions, core algorithms), renaming public interfaces, extracting components.

When optional: Obvious renames (loop variables), extracting pure helpers, changes your existing test suite already covers.