Simplify Complexity

Overview

Core Principle: Move complexity from interfaces to implementations, from callers to callees, and from many places to few. The goal is reducing overall system complexity, not just relocating it.

Three Simplification Levers:

1. •Pull complexity downward (into implementations)
2. •Define errors out of existence (through better semantics)
3. •Make code obvious (reduce reader effort)

When to Use

• •Code is described as "too complex" or "hard to understand"
• •Error handling is verbose or scattered
• •Refactoring for clarity or simplicity
• •Callers are doing work that belongs in modules
• •Configuration parameters proliferate
• •User says: "simplify", "refactor", "too complex", "reduce errors", "clean up"

When NOT to Use

• •Creating new modules from scratch (see: designing-deep-modules)
• •Reviewing code quality (see: reviewing-module-design)
• •Improving names/comments only (see: improving-code-clarity)
• •Fixing bugs in legacy code (see: maintaining-design-quality)
• •Performance optimization (see: optimizing-critical-paths)

Pull Complexity Downward

Decision Procedure

Before adding complexity to an interface (new parameters, new exceptions, new caller responsibilities):

1. Is this complexity closely related to the module's existing functionality?
   NO  → Should it be pulled into a DIFFERENT module?
         YES → Identify correct module, pull there
         NO  → Leave in place (may be inherent to caller's domain)
   YES → Continue

2. Will pulling down simplify code elsewhere in the application?
   NO  → Do not pull down (no benefit)
   YES → Continue

3. Will pulling down simplify the module's interface?
   NO  → Do not pull down (risk of leakage)
   YES → Pull complexity down

All three conditions must be YES to pull down.

Critical Constraint: Pulling down UNRELATED complexity creates information leakage. If the complexity isn't intrinsic to the module's core abstraction, it doesn't belong there—find the right home or leave it with the caller.

Example: Pull Complexity Down

# BEFORE: Caller handles buffering complexity
def read_data(file, buffer_size=4096):
    return file.read(buffer_size)

# Every caller must manage chunking:
chunks = []
while True:
    chunk = read_data(file)
    if not chunk:
        break
    chunks.append(chunk)
data = b''.join(chunks)

# AFTER: Module handles buffering internally
def read_all_data(file):
    """Read entire file, handling buffering internally."""
    chunks = []
    while True:
        chunk = file.read(4096)  # Buffer size is implementation detail
        if not chunk:
            break
        chunks.append(chunk)
    return b''.join(chunks)

# Caller simplified:
data = read_all_data(file)

Configuration Parameters

Configuration parameters represent incomplete solutions. Every parameter pushes complexity to every user/administrator. Prefer dynamic computation over static configuration.

Error Reduction Hierarchy

Apply in order of preference:

Note on "Crash": This is NOT level 4 of a hierarchy—it's a special case for truly unrecoverable errors in application code. Libraries should NEVER crash; they expose errors for callers to decide. "Just crash" applies only when recovery is impossible AND the application type permits it (CLI tools yes, long-running servers rarely).

Error Reduction Decision Procedure

When facing an exception handling decision:

1. Can semantics be redefined to eliminate the error condition?
   YES → Define out of existence
   NO  → Continue

2. Can exception be handled at low level without exposing?
   YES → Mask
   NO  → Continue

3. Can multiple exceptions share the same handling?
   YES → Aggregate
   NO  → Continue

4. Is error rare, unrecoverable, and non-value-critical?
   YES → Just crash
   NO  → Must expose (exception information needed outside module)

Warning Signs

When NOT to Apply Hierarchy

Do NOT apply error reduction in these cases:

Validation Gates

Before applying each technique:

If the answer suggests exposing the error, expose it—even if hierarchy says otherwise.

Sometimes exposing is correct: If exception information is genuinely needed by callers for different handling, exposing it is the right design—not a failure to simplify.

Define-Out Appropriateness Test

Before defining an error out of existence, verify it's an incidental error (safe) not an essential error (must fail fast):

Example: Empty file → empty dict {}

• •Empty file in normal operation? Maybe (new file)
• •Can caller proceed with {}? Depends on context
• •Other detection path? No

Verdict: Context-dependent—not always safe to define out. Ask caller's needs.

Obviousness Techniques

Three Ways to Make Code Obvious

Obviousness Test

If a code reviewer says your code is not obvious, it is not obvious—regardless of how clear it seems to you. Use reviewer feedback to learn what made it nonobvious.

Common Obviousness Problems

Mandatory Output: Show Your Work

Before presenting simplified code, output a technique analysis table:

| Error Condition | Technique | Gate Check | Reasoning |
|-----------------|-----------|------------|-----------|
| [each error]    | [1-4]     | [PASS/FAIL]| [why]     |

This prevents claiming hierarchy application without evidence.

Transformation Checklist (Mandatory Gate)

Do NOT present simplified code until ALL boxes are checked:

• • Walked through EACH level of hierarchy for EACH error condition
• • Documented why earlier levels were rejected (if applicable)
• • Verified validation gates passed for each technique applied
• • Complexity moved to fewer places (not just relocated)
• • Interfaces are simpler than before
• • Callers do less work than before
• • Error handling is consolidated or eliminated
• • Reader needs less context to understand

Anti-Rationalization Table

Principle Conflict Resolution

When simplification techniques conflict with other good practices:

Red Flags

Quick Reference

SIMPLIFICATION PRIORITY ORDER:

1. Can I ELIMINATE this complexity entirely?
   → Redefine semantics, remove special cases

2. Can I CONSOLIDATE this complexity?
   → Pull down into one module, aggregate handlers

3. Can I HIDE this complexity?
   → Mask in implementation, use defaults

4. Can I CLARIFY this complexity?
   → Better names, strategic comments, meet conventions

Do NOT just move complexity around—reduce it.

References: aposd-foundations for complexity symptoms