# BAD: Does multiple things at different levels of abstraction
def process_order(order):
    # Validate
    if order.total < 0:
        raise ValueError("Negative total")
    if not order.items:
        raise ValueError("Empty order")
    # Calculate shipping
    weight = sum(item.weight for item in order.items)
    if weight < 1:
        shipping = 5.99
    elif weight < 5:
        shipping = 12.99
    else:
        shipping = 24.99
    # Apply tax
    tax = order.subtotal * 0.08
    # Charge payment
    stripe.charges.create(amount=int((order.subtotal + shipping + tax) * 100), ...)
    # Send confirmation
    send_email(order.customer.email, "Order confirmed", ...)
    # Update inventory
    for item in order.items:
        db.execute("UPDATE products SET stock = stock - ? WHERE id = ?", item.qty, item.id)

# GOOD: One function per concern, one level of abstraction
def process_order(order):
    validate_order(order)
    shipping = calculate_shipping(order)
    tax = calculate_tax(order)
    charge_payment(order, shipping, tax)
    send_confirmation(order)
    update_inventory(order)

// Pure — easy to test, easy to reason about
function calculateDiscount(price, percentage) {
  return price * (percentage / 100);
}

// Impure — depends on external state, has side effects
function applyDiscount(order) {
  const rate = getDiscountRate();     // External state
  order.total -= order.total * rate;  // Mutation
  logDiscount(order);                 // Side effect
}

// Before
function printReport(order: Order) {
  // Print header
  console.log("===== Order Report =====");
  console.log(`Order #${order.id}`);
  console.log(`Date: ${order.date.toLocaleDateString()}`);
  console.log("");

  // Print items
  for (const item of order.items) {
    console.log(`  ${item.name}  x${item.qty}  $${(item.price * item.qty).toFixed(2)}`);
  }

  // Print totals
  const subtotal = order.items.reduce((sum, i) => sum + i.price * i.qty, 0);
  const tax = subtotal * 0.08;
  console.log("");
  console.log(`  Subtotal: $${subtotal.toFixed(2)}`);
  console.log(`  Tax:      $${tax.toFixed(2)}`);
  console.log(`  Total:    $${(subtotal + tax).toFixed(2)}`);
}

// After
function printReport(order: Order) {
  printHeader(order);
  printLineItems(order.items);
  printTotals(order.items);
}

# Before — adding a new shape requires modifying this function
def calculate_area(shape):
    if shape.type == "circle":
        return math.pi * shape.radius ** 2
    elif shape.type == "rectangle":
        return shape.width * shape.height
    elif shape.type == "triangle":
        return 0.5 * shape.base * shape.height
    else:
        raise ValueError(f"Unknown shape: {shape.type}")

# After — adding a new shape requires only a new class
class Circle:
    def __init__(self, radius): self.radius = radius
    def area(self): return math.pi * self.radius ** 2

class Rectangle:
    def __init__(self, width, height): self.width, self.height = width, height
    def area(self): return self.width * self.height

class Triangle:
    def __init__(self, base, height): self.base, self.height = base, height
    def area(self): return 0.5 * self.base * self.height

// Before — 6 parameters, hard to remember order
public Report Generate(DateTime start, DateTime end, string department,
                        bool includeArchived, string format, int maxResults)

// After — intention-revealing parameter object
public Report Generate(ReportCriteria criteria)

public record ReportCriteria(
    DateTime StartDate,
    DateTime EndDate,
    string Department,
    bool IncludeArchived = false,
    string Format = "pdf",
    int MaxResults = 100
);

// Before
if (password.length < 8) { ... }
if (retries > 3) { ... }
if (role === "admin") { ... }
setTimeout(callback, 86400000);

// After
const MIN_PASSWORD_LENGTH = 8;
const MAX_RETRIES = 3;
const ROLE_ADMIN = "admin";
const ONE_DAY_MS = 24 * 60 * 60 * 1000;

if (password.length < MIN_PASSWORD_LENGTH) { ... }
if (retries > MAX_RETRIES) { ... }
if (role === ROLE_ADMIN) { ... }
setTimeout(callback, ONE_DAY_MS);

# Before — deeply nested, hard to follow
def get_payment_amount(order):
    if order is not None:
        if order.is_confirmed:
            if not order.is_paid:
                if order.total > 0:
                    return order.total
                else:
                    return 0
            else:
                raise AlreadyPaidError()
        else:
            raise NotConfirmedError()
    else:
        raise ValueError("Order is None")

# After — flat, easy to scan
def get_payment_amount(order):
    if order is None:
        raise ValueError("Order is None")
    if not order.is_confirmed:
        raise NotConfirmedError()
    if order.is_paid:
        raise AlreadyPaidError()
    if order.total <= 0:
        return 0
    return order.total

1. Ensure tests pass                ← Green baseline
2. Identify the smell               ← What's wrong?
3. Choose a refactoring             ← Which recipe fits?
4. Apply in small steps             ← One change at a time
5. Run tests after each step        ← Still green?
6. Commit when green                ← Save your progress
7. Repeat until the smell is gone

# WHY — explains a non-obvious business rule or trade-off
# We round to the nearest cent AFTER summing all items to avoid
# accumulated floating-point drift. The old approach (rounding each
# item) caused $0.01 discrepancies on orders with 50+ items.
total = round(sum(item.price * item.qty for item in items), 2)

# WARNING — alerts future developers to a non-obvious constraint
# DO NOT reorder these initialization steps. The renderer must be
# initialized before the input system because it registers event
# handlers that depend on the rendering context.

# TODO / FIXME — tracked, actionable, with ticket reference
# TODO(#234): Replace this linear scan with a spatial index once
# the entity count exceeds 1000 in typical gameplay.

# BAD: Restates the code (just noise)
i += 1  # Increment i by 1

# BAD: Outdated — the code has changed, the comment hasn't
# Returns the user's full name
def get_display_name(user):
    return user.username  # Changed from full_name in v2.3

# BAD: Apology for bad code — refactor instead
# Sorry this is messy, will clean up later (added 2 years ago)