Deep Modules & Complexity — Find the Bug¶

13 snippets where complexity is the accomplice. In each one a real defect hides behind a symptom of complexity — change amplification, obscurity, a leaked dependency, hidden mutable state, or an "it's just one special case" branch nobody tests. The bug is not a typo you can spot by squinting; it is concealed by the system's shape. Find it, name the complexity that hid it, then watch the bug surface the moment the design is simplified.

The thesis, straight from Ousterhout: complexity is anything that makes software hard to understand or modify, and it shows up as three symptoms — change amplification, high cognitive load, and unknown-unknowns — caused by exactly two roots: dependencies and obscurity. Every snippet below is a small, runnable demonstration that those symptoms are not abstract: they are where bugs go to live.

Table of Contents¶

1. How to Use
2. The Map: which complexity hides which bug
3. Snippet 1 — Change amplification: the rate that lives in three places (Go)
4. Snippet 2 — Obscurity: seconds, milliseconds, and a wrong TTL (Python)
5. Snippet 3 — Unknown-unknown: an implicit call-ordering contract (Java)
6. Snippet 4 — Hidden shared mutable state: the cache two paths disagree about (Go)
7. Snippet 5 — Leaked dependency: a helper that assumes sorted input (Python)
8. Snippet 6 — Accidental complexity: the config-driven engine's untested branch (Java)
9. Snippet 7 — The clever general abstraction with a silent edge case (Go)
10. Snippet 8 — "It's just one special case": the branch that mutates the loop bound (Python)
11. Snippet 9 — Temporal coupling across modules: init order (Java)
12. Snippet 10 — Obscurity: a default that means two different things (Go)
13. Snippet 11 — Hidden state: a generator consumed twice (Python)
14. Snippet 12 — Pass-through dependency hides a lost flag (Java)
15. Snippet 13 — Change amplification across the wire: enum drift (Go)
16. Scorecard
17. Related Topics

How to Use¶

1. Read the snippet. Resist the urge to scroll. Ask yourself the literal question: what is the bug, and what shape in this code let it survive code review?
2. Form a hypothesis about the defect and a second hypothesis about the complexity — they are different. The defect is the wrong output; the complexity is the reason a competent engineer wrote it and a competent reviewer approved it.
3. Open the answer. Each one gives you three things: the bug, the complexity that hid it, and the simplification that makes the bug either impossible or impossible to miss.
4. The deepest lesson is in the third part. A simplification that merely fixes this bug is a patch; a simplification that makes the whole class of bug structurally impossible is design. We aim for the second every time.

Difficulty is marked per snippet: 🟢 warm-up · 🟡 needs care · 🔴 you will likely miss it on the first pass.

The Map: which complexity hides which bug¶

Each bug below is filed under the root cause and symptom it best illustrates. Several straddle categories — that is the point. Complexity is not modular.

Snippet 1 — Change amplification: the rate that lives in three places (Go)¶

🟡 Difficulty: needs care

package billing

import "math"

// Tax rate for the EU standard VAT. Used across the billing module.

func PriceWithTax(net float64) float64 {
    return net * 1.20 // includes 20% VAT
}

func TaxComponent(net float64) float64 {
    return net * 0.20 // 20% VAT
}

// Used by the invoice PDF renderer.
func FormatTaxLine(net float64) string {
    tax := net * 0.20
    return "VAT (20%): " + formatMoney(tax)
}

// Reconciliation job: recompute net from a gross total to verify ledger entries.
func NetFromGross(gross float64) float64 {
    // gross = net * (1 + rate)  =>  net = gross / (1 + rate)
    return math.Round(gross/1.2*100) / 100
}

The VAT rate just changed from 20% to 21%. An engineer searches for 0.20, updates TaxComponent and FormatTaxLine, ships it. Reconciliation starts failing intermittently. Where is the bug?

const VATRate = 0.21 // single source of truth

func PriceWithTax(net float64) float64 { return net * (1 + VATRate) }
func TaxComponent(net float64) float64 { return net * VATRate }
func FormatTaxLine(net float64) string {
    pct := int(VATRate * 100)
    return fmt.Sprintf("VAT (%d%%): %s", pct, formatMoney(net*VATRate))
}
func NetFromGross(gross float64) float64 {
    return math.Round(gross/(1+VATRate)*100) / 100
}

Snippet 2 — Obscurity: seconds, milliseconds, and a wrong TTL (Python)¶

🟡 Difficulty: needs care

import time

CACHE_TTL = 300  # 5 minutes


class SessionCache:
    def __init__(self):
        self._store = {}  # key -> (value, stored_at)

    def put(self, key, value):
        # time.time() returns float seconds since epoch
        self._store[key] = (value, time.time())

    def get(self, key):
        entry = self._store.get(key)
        if entry is None:
            return None
        value, stored_at = entry
        if self._now_ms() - stored_at > CACHE_TTL:
            del self._store[key]
            return None
        return value

    def _now_ms(self):
        # other parts of the system log in milliseconds, so we standardized on ms
        return int(time.time() * 1000)

Sessions are expiring almost instantly — users get logged out seconds after logging in. Where is the bug?

class Seconds(float):
    """A duration or instant measured in seconds. Distinct by name at every call site."""


CACHE_TTL = Seconds(300)


class SessionCache:
    def __init__(self, clock=time.monotonic):
        self._store = {}
        self._clock = clock  # monotonic: immune to wall-clock jumps, single unit

    def put(self, key, value):
        self._store[key] = (value, Seconds(self._clock()))

    def get(self, key):
        entry = self._store.get(key)
        if entry is None:
            return None
        value, stored_at = entry
        if Seconds(self._clock()) - stored_at > CACHE_TTL:
            del self._store[key]
            return None
        return value

Snippet 3 — Unknown-unknown: an implicit call-ordering contract (Java)¶

🔴 Difficulty: you will likely miss it

public class ReportBuilder {
    private final List<Row> rows = new ArrayList<>();
    private BigDecimal runningTotal = BigDecimal.ZERO;
    private boolean finalized = false;

    public void addRow(Row row) {
        rows.add(row);
        runningTotal = runningTotal.add(row.amount());
    }

    // Applies the audited rounding policy and locks the report.
    public void finalizeTotals() {
        runningTotal = runningTotal.setScale(2, RoundingMode.HALF_EVEN);
        finalized = true;
    }

    public BigDecimal total() {
        return runningTotal;
    }

    public byte[] renderPdf() {
        // renders rows + total into a PDF
        return Pdf.render(rows, runningTotal);
    }
}

The original report-generation code worked for two years. A new export feature was added by a different team:

public byte[] exportReport(List<Row> data) {
    ReportBuilder b = new ReportBuilder();
    for (Row r : data) b.addRow(r);
    return b.renderPdf();   // new caller
}

Auditors report the new export's totals are occasionally off by a cent versus the legacy report. Where is the bug?

public final class Report {
    private final List<Row> rows;
    private final BigDecimal total;

    private Report(List<Row> rows, BigDecimal total) {
        this.rows = rows;
        this.total = total;
    }

    // The only way to get a Report applies the rounding policy. No ordering to forget.
    public static Report of(List<Row> rows) {
        BigDecimal sum = rows.stream()
            .map(Row::amount)
            .reduce(BigDecimal.ZERO, BigDecimal::add)
            .setScale(2, RoundingMode.HALF_EVEN);
        return new Report(List.copyOf(rows), sum);
    }

    public BigDecimal total() { return total; }
    public byte[] renderPdf() { return Pdf.render(rows, total); }
}

Snippet 4 — Hidden shared mutable state: the cache two paths disagree about (Go)¶

🔴 Difficulty: you will likely miss it

package pricing

var discountCache = map[string]float64{} // userID -> discount fraction, lazily filled

// Called by the cart page.
func DiscountFor(userID string) float64 {
    if d, ok := discountCache[userID]; ok {
        return d
    }
    d := computeDiscount(userID) // hits the DB, expensive
    discountCache[userID] = d
    return d
}

// Called by an admin tool when a user's tier changes.
func RefreshTier(userID string, newTier string) {
    saveTierToDB(userID, newTier)
    delete(discountCache, userID) // invalidate so next read recomputes
}

// Called by the checkout service to compute the final charge.
func FinalPrice(userID string, subtotal float64) float64 {
    discount := DiscountFor(userID)
    // ... 200 lines later, in the same request, after a slow inventory check ...
    return subtotal * (1 - discountCache[userID])
}

A user is charged the wrong amount during checkout, but only sometimes, and only when an admin happens to be active. Where is the bug?

func FinalPrice(userID string, subtotal float64) float64 {
    discount := DiscountFor(userID) // read once
    // ... slow inventory check ...
    return subtotal * (1 - discount) // use the local snapshot, never the global
}

Snippet 5 — Leaked dependency: a helper that assumes sorted input (Python)¶

🟡 Difficulty: needs care

def median(values):
    """Return the median. Assumes `values` is sorted ascending (caller's job)."""
    n = len(values)
    mid = n // 2
    if n % 2 == 1:
        return values[mid]
    return (values[mid - 1] + values[mid]) / 2


def p95_latency(samples):
    samples.sort()
    idx = int(len(samples) * 0.95)
    return samples[idx]


def dashboard_stats(raw_latencies):
    return {
        "median_ms": median(raw_latencies),   # caller A
        "p95_ms": p95_latency(raw_latencies),  # caller B
    }

The p95 number on the dashboard looks right. The median looks wrong — far higher than it should be. Where is the bug?

def median(values):
    s = sorted(values)  # owns its precondition; cannot be fed unsorted
    n = len(s)
    mid = n // 2
    if n % 2 == 1:
        return s[mid]
    return (s[mid - 1] + s[mid]) / 2


def p95_latency(samples):
    s = sorted(samples)  # no in-place mutation of the caller's list
    return s[int(len(s) * 0.95)]

Snippet 6 — Accidental complexity: the config-driven engine's untested branch (Java)¶

🔴 Difficulty: you will likely miss it

// A "flexible" rules engine. Behavior is driven by a config map so that
// "business can change rules without a deploy."
public class FeeEngine {

    public BigDecimal computeFee(Account acct, Map<String, Object> rules) {
        BigDecimal base = (BigDecimal) rules.getOrDefault("base", BigDecimal.ZERO);
        String mode = (String) rules.getOrDefault("mode", "flat");

        switch (mode) {
            case "flat":
                return base;
            case "percent":
                BigDecimal pct = (BigDecimal) rules.get("percent");
                return acct.balance().multiply(pct);
            case "tiered":
                BigDecimal rate = tierRate(acct, rules);
                // tiered fee = base + balance * tierRate
                return base.add(acct.balance().multiply(rate));
            case "percent_capped":
                BigDecimal p = (BigDecimal) rules.get("percent");
                BigDecimal cap = (BigDecimal) rules.get("cap");
                BigDecimal raw = acct.balance().multiply(p);
                return raw.min(cap);   // cap the fee
            default:
                return base;
        }
    }
    // ... tierRate(...) ...
}

The flat, percent, and tiered modes are battle-tested. percent_capped was added last quarter for one enterprise customer and "worked in the demo." That customer is now being undercharged on every large account. Where is the bug?

sealed interface FeeRule permits Flat, Percent, Tiered, PercentCapped {}
record Flat(BigDecimal base) implements FeeRule {}
record Percent(BigDecimal pct) implements FeeRule {}
record Tiered(BigDecimal base, TierTable tiers) implements FeeRule {}
record PercentCapped(BigDecimal pct, BigDecimal cap) implements FeeRule {} // cap is required

BigDecimal computeFee(Account acct, FeeRule rule) {
    return switch (rule) {
        case Flat f          -> f.base();
        case Percent p       -> acct.balance().multiply(p.pct());
        case Tiered t        -> t.base().add(acct.balance().multiply(t.tiers().rateFor(acct)));
        case PercentCapped c -> acct.balance().multiply(c.pct()).min(c.cap());
        // no default: the compiler enforces exhaustiveness
    };
}

Snippet 7 — The clever general abstraction with a silent edge case (Go)¶

🔴 Difficulty: you will likely miss it

// A "clever" generic memoizer: wraps any 1-arg function and caches results.
func Memoize[K comparable, V any](f func(K) (V, error)) func(K) (V, error) {
    cache := map[K]V{}
    return func(k K) (V, error) {
        if v, ok := cache[k]; ok {
            return v, nil
        }
        v, err := f(k)
        if err != nil {
            return v, err
        }
        cache[k] = v
        return v, nil
    }
}

// Usage: memoize an expensive remote config lookup.
var loadConfig = Memoize(func(env string) (Config, error) {
    return fetchConfigFromRemote(env) // network call
})

loadConfig("prod") is called from many goroutines. Most of the time it returns the right config. Occasionally a caller gets a zero-value Config{} with a nil error, and the service silently runs with empty config. Where is the bug?

func Memoize[K comparable, V any](f func(K) (V, error)) func(K) (V, error) {
    var mu sync.Mutex
    type result struct {
        v   V
        err error
    }
    cache := map[K]result{}
    return func(k K) (V, error) {
        mu.Lock()
        if r, ok := cache[k]; ok {
            mu.Unlock()
            return r.v, r.err
        }
        mu.Unlock()

        v, err := f(k)

        mu.Lock()
        cache[k] = result{v, err} // cache the outcome, including errors if desired
        mu.Unlock()
        return v, err
    }
}

Snippet 8 — "It's just one special case": the branch that mutates the loop bound (Python)¶

🟡 Difficulty: needs care

def apply_promotions(cart_items, promos):
    """
    cart_items: list of {"sku": str, "qty": int, "price": float}
    promos: list of free-gift promos that *append* a free item when triggered.
    """
    total = 0.0
    i = 0
    n = len(cart_items)
    while i < n:
        item = cart_items[i]
        line = item["qty"] * item["price"]
        total += line

        # "It's just one special case": buy-3-get-1-free adds a free unit as a new line.
        for promo in promos:
            if item["sku"] == promo["sku"] and item["qty"] >= promo["min_qty"]:
                cart_items.append({"sku": item["sku"], "qty": 1, "price": 0.0})
        i += 1
    return total

For most carts the total is correct. For carts that trigger a free-gift promo, the server occasionally hangs or returns a total that depends on how many promos exist. Where is the bug?

def apply_promotions(cart_items, promos):
    gift_lines = [
        {"sku": item["sku"], "qty": 1, "price": 0.0}
        for item in cart_items
        for promo in promos
        if item["sku"] == promo["sku"] and item["qty"] >= promo["min_qty"]
    ]
    priced = cart_items + gift_lines           # new list; input untouched
    total = sum(it["qty"] * it["price"] for it in priced)
    return total, priced                        # gifts returned explicitly, not smuggled into input

Snippet 9 — Temporal coupling across modules: init order (Java)¶

🔴 Difficulty: you will likely miss it

public final class FeatureFlags {
    private static Map<String, Boolean> flags = Map.of(); // empty until loaded

    public static void load(ConfigSource source) {
        flags = source.readFlags();
    }

    public static boolean isEnabled(String name) {
        return flags.getOrDefault(name, false);
    }
}

public class PaymentRouter {
    // Field initializer — runs when PaymentRouter is constructed.
    private final boolean useNewProcessor = FeatureFlags.isEnabled("new_payment_processor");

    public PaymentResult charge(Charge c) {
        return useNewProcessor ? newProcessor.charge(c) : legacyProcessor.charge(c);
    }
}

// In main():
public static void main(String[] args) {
    PaymentRouter router = new PaymentRouter();   // (A)
    FeatureFlags.load(new FileConfigSource());    // (B)
    server.start(router);
}

The new_payment_processor flag is set to true in config, was tested on staging, and the rollout was approved. In production, 100% of traffic still hits the legacy processor. No errors, no logs. Where is the bug?

public class PaymentRouter {
    private final FeatureFlags flags; // explicit dependency, injected

    public PaymentRouter(FeatureFlags flags) {
        this.flags = flags;
    }

    public PaymentResult charge(Charge c) {
        // read at the moment of decision — no frozen snapshot, no init-order trap
        boolean useNew = flags.isEnabled("new_payment_processor");
        return useNew ? newProcessor.charge(c) : legacyProcessor.charge(c);
    }
}

Snippet 10 — Obscurity: a default that means two different things (Go)¶

🟡 Difficulty: needs care

type RetryPolicy struct {
    MaxAttempts int           // how many times to try
    Timeout     time.Duration // per-attempt timeout
}

// Run executes fn under the policy. A zero-value RetryPolicy means "use defaults".
func Run(p RetryPolicy, fn func() error) error {
    if p.MaxAttempts == 0 {
        p.MaxAttempts = 3 // default
    }
    if p.Timeout == 0 {
        p.Timeout = 5 * time.Second // default
    }
    var err error
    for i := 0; i < p.MaxAttempts; i++ {
        if err = callWithTimeout(p.Timeout, fn); err == nil {
            return nil
        }
    }
    return err
}

// A caller that explicitly wants "try exactly once, no retries":
func ChargeOnce(charge Charge) error {
    return Run(RetryPolicy{MaxAttempts: 1, Timeout: 2 * time.Second}, func() error {
        return gateway.Charge(charge) // MUST NOT run more than once
    })
}

// A different caller that wants "try once" but writes it the obvious way:
func NotifyOnce(n Notification) error {
    return Run(RetryPolicy{MaxAttempts: 0, Timeout: time.Second}, func() error {
        return notifier.Send(n) // author meant "no retries"
    })
}

ChargeOnce works. NotifyOnce was written by someone who reasoned "zero retries = MaxAttempts: 0" — and notifications are being sent three times. Where is the bug?

type RetryPolicy struct {
    MaxAttempts int           // always a real count; no magic zero
    Timeout     time.Duration
}

// DefaultRetryPolicy is the single, named source of defaults.
func DefaultRetryPolicy() RetryPolicy {
    return RetryPolicy{MaxAttempts: 3, Timeout: 5 * time.Second}
}

func Run(p RetryPolicy, fn func() error) error {
    if p.MaxAttempts < 1 {
        return fmt.Errorf("MaxAttempts must be >= 1, got %d", p.MaxAttempts) // loud, not silent
    }
    var err error
    for i := 0; i < p.MaxAttempts; i++ {
        if err = callWithTimeout(p.Timeout, fn); err == nil {
            return nil
        }
    }
    return err
}

// "Exactly once" is now unambiguous and validated:
func NotifyOnce(n Notification) error {
    return Run(RetryPolicy{MaxAttempts: 1, Timeout: time.Second}, func() error {
        return notifier.Send(n)
    })
}

Snippet 11 — Hidden state: a generator consumed twice (Python)¶

🟡 Difficulty: needs care

def parse_transactions(rows):
    """Yields Transaction objects from raw CSV rows (lazy)."""
    for row in rows:
        yield Transaction(amount=float(row["amount"]), kind=row["kind"])


def reconcile(rows):
    txns = parse_transactions(rows)

    total_debits = sum(t.amount for t in txns if t.kind == "debit")
    total_credits = sum(t.amount for t in txns if t.kind == "credit")

    if total_debits != total_credits:
        raise LedgerImbalance(total_debits, total_credits)
    return total_debits

Every reconciliation that should balance now raises LedgerImbalance, reporting total_credits == 0. Where is the bug?

def parse_transactions(rows):
    return [Transaction(amount=float(r["amount"]), kind=r["kind"]) for r in rows]  # a real list


def reconcile(rows):
    txns = parse_transactions(rows)
    total_debits = sum(t.amount for t in txns if t.kind == "debit")
    total_credits = sum(t.amount for t in txns if t.kind == "credit")
    if total_debits != total_credits:
        raise LedgerImbalance(total_debits, total_credits)
    return total_debits

def reconcile(rows):
    debits = credits = 0.0
    for t in parse_transactions(rows):  # one pass, no second consumption
        if t.kind == "debit":
            debits += t.amount
        elif t.kind == "credit":
            credits += t.amount
    if debits != credits:
        raise LedgerImbalance(debits, credits)
    return debits

Snippet 12 — Pass-through dependency hides a lost flag (Java)¶

🔴 Difficulty: you will likely miss it

public class OrderService {
    public void placeOrder(Order order, boolean dryRun) {
        validate(order);
        inventoryService.reserve(order, dryRun);
    }
}

public class InventoryService {
    public void reserve(Order order, boolean dryRun) {
        for (Item item : order.items()) {
            warehouse.allocate(item, dryRun);
        }
        // emit a "stock reserved" event so the analytics pipeline updates
        eventBus.publish(new StockReservedEvent(order.id()));
    }
}

public class Warehouse {
    public void allocate(Item item, boolean dryRun) {
        if (dryRun) return;            // dry run: don't actually decrement
        stock.put(item.sku(), stock.get(item.sku()) - item.qty());
    }
}

Running a dryRun order (a "what-if" preview that must change nothing) leaves the warehouse stock untouched — good. But analytics dashboards show phantom reservations after every preview. Where is the bug?

public class OrderService {
    // Preview never touches anything that has a side effect.
    public OrderPreview preview(Order order) {
        validate(order);
        return inventoryService.computeReservation(order); // pure: returns what *would* happen
    }

    // Commit performs all side effects, including the event.
    public void placeOrder(Order order) {
        validate(order);
        Reservation r = inventoryService.computeReservation(order);
        inventoryService.commit(r);                 // decrements stock
        eventBus.publish(new StockReservedEvent(order.id())); // only on the real path
    }
}

Snippet 13 — Change amplification across the wire: enum drift (Go)¶

🔴 Difficulty: you will likely miss it

// service A (producer)
type Status int

const (
    StatusPending Status = iota // 0
    StatusActive                // 1
    StatusSuspended             // 2
    StatusClosed                // 3
)

func (s Status) String() string {
    return [...]string{"pending", "active", "suspended", "closed"}[s]
}

// service A serializes status as its integer over a message queue.
func (s Status) Marshal() int { return int(s) }

// ---- separate repo: service B (consumer) ----
// service B has its own copy of the enum (no shared schema package).
const (
    bPending   = 0
    bActive    = 1
    bClosed    = 2 // B was written before "suspended" existed
    bSuspended = 3
)

func handle(statusCode int) {
    switch statusCode {
    case bClosed: // 2
        archiveAccount()
    case bSuspended: // 3
        notifyComplianceTeam()
    }
}

Service A added StatusSuspended between Active and Closed last sprint. Since then, accounts that A marks suspended are being archived by B, and genuinely closed accounts trigger spurious compliance notifications. Where is the bug?

// shared schema package, imported by BOTH services.
package status

type Status string

const (
    Pending   Status = "pending"
    Active    Status = "active"
    Suspended Status = "suspended"
    Closed    Status = "closed"
)

func Parse(s string) (Status, error) {
    switch Status(s) {
    case Pending, Active, Suspended, Closed:
        return Status(s), nil
    default:
        return "", fmt.Errorf("unknown status %q", s) // unknown value fails loudly, never misread
    }
}

Scorecard¶

Track which complexity-shapes you caught unaided. The pattern you miss is the one your codebase is most exposed to.

Reading your score:

• Missed mostly 🟡: you read code line-by-line and trust names and comments. Practice distrusting unenforced contracts — units, sortedness, "assumes X" docstrings.
• Missed mostly 🔴: you reason within one function or one file. These bugs live between modules — in call order, shared globals, wire formats, and pass-through chains. Train yourself to ask "what does this depend on that isn't in the signature?"
• Caught everything: then notice the meta-pattern. In every fix, the winning move was the same — make the bad state unrepresentable, not "be more careful." Carefulness does not scale; structure does.

Related Topics¶

• README.md — the chapter's positive rules: the three symptoms, two causes, and strategic-vs-tactical programming.
• junior.md — the foundational version of these ideas, with the smallest examples.
• tasks.md — exercises that ask you to introduce complexity and then remove it, the inverse of this file.
• optimize.md — the same code paths, this time hiding performance defects instead of correctness defects.
• Chapter index — where Deep Modules & Complexity sits among the Clean Code chapters.
• Anti-Patterns — the named smells (tactical tornado, dependency creep) that produce these bugs in the first place.
• Refactoring — the mechanical moves (Extract Function, Replace Conditional with Polymorphism, Introduce Parameter Object) that perform the simplifications shown in each answer.