Principle: Optimize for deletion

Code becomes hard to remove or replace because it's deeply entangled with other parts of the system.

Write code that's easy to delete:

1. Isolate third-party dependencies:

# BAD: Stripe API spread everywhere
stripe.Charge.create(amount=1000, ...)  # In 50 files

# GOOD: Wrapped in one module
# payments.py
def charge(amount, token):
    return stripe.Charge.create(amount=amount, source=token)
# Switching to another provider = change one file

1. Feature flags over branching:

• Features behind flags can be deleted by flipping a switch
• No merge required, no deployment

1. Vertical slices over horizontal layers:

• Feature in one directory > spread across many
• Delete the directory = feature removed

1. Avoid shared state:

• Global state makes everything depend on everything
• Pass dependencies explicitly

1. Small, independent modules:

• If deleting a module requires changes in 20 other files, it's too coupled
• Aim for: delete the module, update 1-2 import sites

Litmus test: How many files do you need to touch to completely remove this feature? Fewer = better.

The ability to delete code is a measure of how well-structured it is. Deletable code has clear boundaries, explicit dependencies, and minimal coupling.

Software architecture and code organization decisions