code-refactoring

name	code-refactoring
description	Code refactoring patterns and techniques for improving code quality without changing behavior. Use for cleaning up legacy code, reducing complexity, or improving maintainability.
source	https://github.com/Ethanon/developer.ai
license	MIT

Code Refactoring

Refactoring Principles

When to Refactor

• Before adding new features (make change easy, then make easy change)
• After getting tests passing (red-green-refactor)
• When you see code smells
• During code review feedback

When NOT to Refactor

• Without tests covering the code
• Under tight deadlines with no safety net
• Code that will be replaced soon
• When you don't understand what the code does

Common Code Smells

Long Methods

# BEFORE: Method doing too much
def process_order(order: Order) -> None:
    # 100 lines of validation, calculation, notification, logging...

# AFTER: Extract into focused methods
def process_order(order: Order) -> None:
    validate_order(order)
    total = calculate_total(order)
    save_order(order, total)
    notify_customer(order)

Deeply Nested Conditionals

# BEFORE: Arrow code
def get_discount(user: User, order: Order) -> float:
    if user:
        if user.is_premium:
            if order.total > 100:
                if len(order.items) > 5:
                    return 0.2
    return 0.0

# AFTER: Early returns (guard clauses)
def get_discount(user: User, order: Order) -> float:
    if not user:
        return 0.0
    if not user.is_premium:
        return 0.0
    if order.total <= 100:
        return 0.0
    if len(order.items) <= 5:
        return 0.0
    return 0.2

Primitive Obsession

# BEFORE: Primitives everywhere
def create_user(name: str, email: str, phone: str) -> User:
    if '@' not in email:
        raise ValueError('Invalid email')
    # more validation...

# AFTER: Value objects
from dataclasses import dataclass

@dataclass(frozen=True)
class Email:
    value: str

    def __post_init__(self) -> None:
        if '@' not in self.value:
            raise ValueError('Invalid email')

    def __str__(self) -> str:
        return self.value

def create_user(name: str, email: Email, phone: Phone) -> User:
    # Email is already validated
    ...

Feature Envy

# BEFORE: Method uses another object's data extensively
def calculate_shipping(order: Order) -> float:
    address = order.customer.address
    weight = sum(item.weight for item in order.items)
    distance = calculate_distance(address.zip_code)
    return weight * distance * 0.01

# AFTER: Move method to where the data is
class Order:
    def calculate_shipping(self) -> float:
        return self.total_weight * self.customer.shipping_distance * 0.01

Refactoring Techniques

Extract Method

# Identify a code block that does one thing
# Move it to a new function with a descriptive name
# Replace original code with the function call

def print_report(data: ReportData) -> None:
    # Extract this block into a function
    _print_header(data)
    # ... rest of report

def _print_header(data: ReportData) -> None:
    header = f"Report: {data.title}\nDate: {data.date}\n{'=' * 40}"
    print(header)

Replace Conditional with Polymorphism

# BEFORE: if/elif on type
def get_area(shape: Shape) -> float:
    if shape.type == 'circle':
        return math.pi * shape.radius ** 2
    elif shape.type == 'rectangle':
        return shape.width * shape.height
    elif shape.type == 'triangle':
        return shape.base * shape.height / 2
    raise ValueError(f'Unknown shape: {shape.type}')

# AFTER: Polymorphic classes
from abc import ABC, abstractmethod

class Shape(ABC):
    @abstractmethod
    def get_area(self) -> float: ...

class Circle(Shape):
    def __init__(self, radius: float) -> None:
        self.radius = radius

    def get_area(self) -> float:
        return math.pi * self.radius ** 2

class Rectangle(Shape):
    def __init__(self, width: float, height: float) -> None:
        self.width = width
        self.height = height

    def get_area(self) -> float:
        return self.width * self.height

Introduce Parameter Object

# BEFORE: Too many parameters
def search_products(
    query: str,
    min_price: float,
    max_price: float,
    category: str,
    in_stock: bool,
    sort_by: str,
    sort_order: str,
) -> list[Product]: ...

# AFTER: Parameter object (dataclass or TypedDict)
from dataclasses import dataclass, field

@dataclass
class SearchParams:
    query: str
    price_range: tuple[float, float] = (0.0, float('inf'))
    category: str | None = None
    in_stock: bool | None = None
    sort_by: str = 'relevance'
    sort_order: str = 'asc'

def search_products(params: SearchParams) -> list[Product]: ...

Replace Magic Numbers with Constants

# BEFORE
if user.age >= 18 and order.total >= 50:
    apply_discount(order, 0.1)

# AFTER
MINIMUM_AGE = 18
DISCOUNT_THRESHOLD = 50.0
STANDARD_DISCOUNT = 0.1

if user.age >= MINIMUM_AGE and order.total >= DISCOUNT_THRESHOLD:
    apply_discount(order, STANDARD_DISCOUNT)

Safe Refactoring Process

1. Ensure tests exist - Write tests if they don't (pytest to confirm they pass)
2. Make small changes - One refactoring at a time
3. Run tests after each change - pytest to catch regressions immediately
4. Commit frequently - Easy to revert if something breaks
5. Review the diff - Make sure behavior hasn't changed

Python-Specific Notes

• Use mypy or pyright for type checking after refactoring — rename regressions show up immediately.
• ruff can automate many simple refactors (unused imports, simplifiable conditionals).
• Prefer @dataclass(frozen=True) for value objects over mutable classes.
• Use Protocol instead of ABC when the interface is structural (duck typing): callers don't need to import or inherit from the protocol.
• functools.lru_cache / functools.cache can replace memoization boilerplate.

Refactoring Checklist

• Tests pass before starting (pytest)
• Each change is small and focused
• Tests pass after each change (pytest)
• Type checker passes (mypy/pyright)
• No behavior changes (only structure)
• Code is more readable than before
• Commit message explains the refactoring