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