INSTRUCTIONS

Apply the code optimization priority framework: sacrifice lower priorities to improve higher ones.

The Priority Hierarchy

State > Coupling > Complexity > Code

Priority	Focus	Why It Matters
1. State	Minimize mutable state	Stateless code works identically in sequential, parallel, and distributed contexts
2. Coupling	Reduce dependencies	Loose coupling enables independent change and testing
3. Complexity	Simplify logic	Lower cognitive load, fewer bugs
4. Code	Reduce volume	Less to read and maintain

Core Principle

"It's okay to increase coupling if it makes your code more stateless."

Each level can be sacrificed to improve a higher-priority concern:

• More code is acceptable for less complexity
• More complexity is acceptable for less coupling
• More coupling is acceptable for less state

Decision Framework

When evaluating design choices:

1. Does Option A have less mutable state than Option B?
   Yes → Prefer Option A (even if more coupled/complex/verbose)
   No  ↓
2. Does Option A have less coupling than Option B?
   Yes → Prefer Option A (even if more complex/verbose)
   No  ↓
3. Does Option A have less complexity than Option B?
   Yes → Prefer Option A (even if more verbose)
   No  ↓
4. Prefer the option with less code

Why This Order?

State is hardest to reason about:

• Requires tracking "before" and "after" conditions
• Creates implicit dependencies between operations
• Breaks parallelization and distribution
• Explodes test setup complexity

Beginners optimize the wrong thing:

• Code volume is most visible, so it gets optimized first
• But state, coupling, and complexity matter more for maintainability
• Experience teaches that a few extra lines are cheap; hidden state is expensive

Practical Examples

Prefer Stateless (Accept More Coupling)

# More state, less coupling
class Processor:
    def __init__(self):
        self.result = None

    def process(self, data):
        self.result = transform(data)

    def get_result(self):
        return self.result

# Less state, more coupling (PREFERRED)
def process(data, transformer):
    return transformer(data)

Prefer Less Coupling (Accept More Code)

# Less code, more coupling
def create_user(data):
    user = User(**data)
    db.save(user)           # Coupled to global db
    email.send_welcome()    # Coupled to global email
    return user

# More code, less coupling (PREFERRED)
def create_user(data, repository, notifier):
    user = User(**data)
    repository.save(user)
    notifier.send_welcome(user)
    return user

Prefer Less Complexity (Accept More Code)

# Less code, more complexity
result = data if condition else (default if not other else fallback)

# More code, less complexity (PREFERRED)
if condition:
    result = data
elif other:
    result = fallback
else:
    result = default

Review Checklist

When reviewing code or design:

• Is state being introduced where a pure function would work?
• Are global/shared dependencies creating hidden coupling?
• Is clever code sacrificing readability for brevity?
• Is the author optimizing for code volume over deeper concerns?

Anti-Patterns

Anti-Pattern	Problem	Better Approach
Global singletons	Maximum coupling + hidden state	Dependency injection
Mutable shared state	Race conditions, test complexity	Immutable data, message passing
Clever one-liners	Complexity hidden in density	Explicit multi-line logic
Premature DRY	Wrong abstraction, coupling	Tolerate duplication until pattern is clear

Integration with Other Practices

This framework complements:

• Tidy First: Structural improvements often reduce coupling
• TDD: Tests reveal hidden state and coupling problems early
• Refactoring: Many patterns specifically target state and coupling

Reference

Based on: curun1r's comment on Hacker News, attributed to Sandi Metz's design principles