Emergent Design — Find the Bug¶

12 buggy snippets where the defect lives inside an over-engineered abstraction: a premature DRY merge, a speculative plugin hook, a generic engine, a "future-proof" config layer. The code looks elegant. That elegance is the bug. Find it, then notice that the fix is almost always inline and split — collapse the wrong abstraction and let the right one emerge later.

Table of Contents¶

1. How to Use
2. The Shape of an Over-Engineering Bug
3. Snippets
4. Snippet 1 — Wrong DRY: one rule change corrupts the other caller (Python)
5. Snippet 2 — Shared range helper hides inclusive vs exclusive (Go)
6. Snippet 3 — Config-driven engine with one untested branch (Java)
7. Snippet 4 — Speculative strategy hook with a silent default (Go)
8. Snippet 5 — Generic Manager<T> whose assumption breaks for a new T (Java)
9. Snippet 6 — YAGNI caching layer returns stale data (Python)
10. Snippet 7 — DRY-ed validation that needed to diverge (Python)
11. Snippet 8 — Premature base class forces a wrong default (Java)
12. Snippet 9 — Over-general formatter swallows a timezone (Go)
13. Snippet 10 — Speculative event bus drops the only listener (Python)
14. Snippet 11 — Generic retry wrapper retries a non-idempotent call (Go)
15. Snippet 12 — Parameterized "do everything" method with a flag collision (Java)
16. Scorecard
17. Related Topics

How to Use¶

Read each snippet before opening the answer. For every one, ask the three questions that expose an over-engineering bug:

1. Was this abstraction extracted from one example or two? A shared function born from a single use case has no evidence about which parts are truly common. The first divergent requirement breaks it.
2. Does one caller silently depend on behavior another caller doesn't want? Wrong DRY couples callers through shared code. A change made for one caller lands on the other.
3. Is there a branch / hook / type parameter that no real caller exercises today? Speculative generality ships untested code paths. The day a second consumer arrives, the unexercised branch runs for the first time — in production.

Try to name the defect and write the fix. Then check yourself against the collapsible answer. Track your score on the Scorecard.

The fix you reach for should usually feel like a step backward: delete the abstraction, duplicate the code, and wait for the real pattern to emerge from two or three concrete cases. That is the discipline of emergent design — duplication is cheaper to fix than the wrong abstraction.

The Shape of an Over-Engineering Bug¶

Most bugs in this file follow one lifecycle. Recognizing it lets you spot the others before they bite.

The crash never comes. That is what makes these bugs dangerous — the abstraction absorbs the divergence instead of rejecting it, and you ship a confidently wrong answer.

Snippets¶

Snippet 1 — Wrong DRY: one rule change corrupts the other caller (Python)¶

Difficulty: 🟢 Junior

Two screens display money. Someone noticed both formatted currency and "DRY-ed" them into one helper. Months later, the invoice team asks for accounting-style negatives — parentheses instead of a minus sign.

def format_money(amount: float) -> str:
    """Shared by the cart UI and the invoice PDF generator."""
    sign = "-" if amount < 0 else ""
    return f"{sign}${abs(amount):,.2f}"


# --- cart_view.py ---
def cart_line(item) -> str:
    return f"{item.name}: {format_money(item.price)}"


# --- invoice_pdf.py ---
def invoice_line(entry) -> str:
    return f"{entry.description}  {format_money(entry.amount)}"


# The invoice team's change request: show negatives in accounting style, e.g. ($12.00).
# An engineer edits the shared helper:
def format_money(amount: float) -> str:
    if amount < 0:
        return f"(${abs(amount):,.2f})"        # accounting style
    return f"${amount:,.2f}"

What's wrong?

def _format_amount(amount: float) -> str:
    return f"${abs(amount):,.2f}"

def cart_money(amount: float) -> str:
    return f"-{_format_amount(amount)}" if amount < 0 else _format_amount(amount)

def invoice_money(amount: float) -> str:
    return f"({_format_amount(amount)})" if amount < 0 else _format_amount(amount)

Snippet 2 — Shared range helper hides inclusive vs exclusive (Go)¶

Difficulty: 🟢 Junior

A pagination helper and a date-range report both needed "a range of values." They were unified into one Range builder.

package report

// Range builds [start, end] — used by pagination AND date reports.
type Range struct {
    Start int
    End   int
}

// Values returns every integer in the range, inclusive of both ends.
func (r Range) Values() []int {
    out := make([]int, 0, r.End-r.Start+1)
    for v := r.Start; v <= r.End; v++ {
        out = append(out, v)
    }
    return out
}

// --- pagination.go ---
// Page 0 should show rows [0..pageSize), i.e. pageSize rows starting at 0.
func PageRows(page, pageSize int) []int {
    start := page * pageSize
    r := Range{Start: start, End: start + pageSize}
    return r.Values()
}

// --- daily_report.go ---
// Days 1..31 of a month, both ends shown to the user.
func MonthDays(daysInMonth int) []int {
    return Range{Start: 1, End: daysInMonth}.Values()
}

What's wrong?

func PageRows(page, pageSize int) []int {
    start := page * pageSize
    out := make([]int, 0, pageSize)
    for v := start; v < start+pageSize; v++ { // half-open: < not <=
        out = append(out, v)
    }
    return out
}

Snippet 3 — Config-driven engine with one untested branch (Java)¶

Difficulty: 🟡 Middle

To "avoid hardcoding business rules," a team built a discount engine driven by a config table. Only PERCENT discounts have ever been configured in production. FIXED was added "for completeness."

public enum DiscountType { PERCENT, FIXED }

public record DiscountRule(DiscountType type, BigDecimal value) {}

public class DiscountEngine {

    public BigDecimal apply(BigDecimal price, DiscountRule rule) {
        switch (rule.type()) {
            case PERCENT:
                // value is a percentage, e.g. 15 means 15% off
                return price.subtract(
                    price.multiply(rule.value()).divide(BigDecimal.valueOf(100)));
            case FIXED:
                // value is an absolute amount off, e.g. 20 means $20 off
                return price.subtract(rule.value());
            default:
                return price;
        }
    }
}

What's wrong?

public BigDecimal apply(BigDecimal price, DiscountRule rule) {
    BigDecimal discounted = switch (rule.type()) {
        case PERCENT -> price.subtract(
            price.multiply(rule.value()).divide(BigDecimal.valueOf(100)));
        case FIXED   -> price.subtract(rule.value());
    };
    return discounted.max(BigDecimal.ZERO); // price can never go negative
}

Snippet 4 — Speculative strategy hook with a silent default (Go)¶

Difficulty: 🟡 Middle

A notification sender was built with a pluggable RateLimiter strategy "so we can swap algorithms later." Only one limiter was ever wired up — except in one construction path.

package notify

type RateLimiter interface {
    Allow(userID string) bool
}

type Sender struct {
    limiter RateLimiter
    gateway Gateway
}

// NewSender wires the production token-bucket limiter.
func NewSender(g Gateway) *Sender {
    return &Sender{limiter: NewTokenBucket(100), gateway: g}
}

// Send checks the rate limit, then delivers.
func (s *Sender) Send(userID, msg string) error {
    if s.limiter == nil || s.limiter.Allow(userID) {
        return s.gateway.Deliver(userID, msg)
    }
    return ErrRateLimited
}

// --- elsewhere, a "lightweight" constructor added for a batch job ---
func NewBatchSender(g Gateway) *Sender {
    // Batch jobs don't need per-user limiting, so we skip the limiter.
    return &Sender{gateway: g}
}

What's wrong?

if s.limiter == nil || s.limiter.Allow(userID) {

type NoLimit struct{}
func (NoLimit) Allow(string) bool { return true }

func NewBatchSender(g Gateway) *Sender {
    // Explicit: batch jobs opt OUT of limiting on purpose.
    return &Sender{limiter: NoLimit{}, gateway: g}
}

func (s *Sender) Send(userID, msg string) error {
    if s.limiter.Allow(userID) { // no nil branch; limiter is always set
        return s.gateway.Deliver(userID, msg)
    }
    return ErrRateLimited
}

Snippet 5 — Generic Manager<T> whose assumption breaks for a new T (Java)¶

Difficulty: 🟡 Middle

A generic CacheManager<T> was extracted from a User cache so it could "work with any entity." A new Session entity reuses it.

public class CacheManager<T> {
    private final Map<String, T> store = new ConcurrentHashMap<>();
    private final Function<T, String> keyOf;

    public CacheManager(Function<T, String> keyOf) {
        this.keyOf = keyOf;
    }

    public void put(T item) {
        store.put(keyOf.apply(item), item);  // dedupe by key
    }

    public T get(String key) {
        return store.get(key);
    }

    public int size() {
        return store.size();
    }
}

// Original, fine: every User has a stable, unique id.
CacheManager<User> users = new CacheManager<>(User::id);

// New use case, six months later:
CacheManager<Session> sessions = new CacheManager<>(s -> s.userId());

What's wrong?

// Option A — key by the genuinely-unique field:
CacheManager<Session> sessions = new CacheManager<>(Session::sessionId);

// Option B — if you must look up by userId, the structure is a multimap,
// which is a DIFFERENT abstraction, not a parameterization of the same one:
Map<String, List<Session>> byUser = new ConcurrentHashMap<>();

Snippet 6 — YAGNI caching layer returns stale data (Python)¶

Difficulty: 🟡 Middle

Nobody had a performance problem, but a "for scale" caching decorator was added to the settings lookup anyway.

import functools

@functools.lru_cache(maxsize=None)
def get_feature_flag(flag_name: str) -> bool:
    """Reads the flag from the database. Cached 'for scale'."""
    row = db.query(
        "SELECT enabled FROM feature_flags WHERE name = %s", flag_name
    )
    return bool(row.enabled)


# --- admin_panel.py ---
def toggle_flag(flag_name: str, enabled: bool) -> None:
    db.execute(
        "UPDATE feature_flags SET enabled = %s WHERE name = %s",
        enabled, flag_name,
    )
    # Flag is updated in the DB. Done.


# --- request_handler.py ---
def handle(request):
    if get_feature_flag("new_checkout"):
        return new_checkout(request)
    return old_checkout(request)

What's wrong?

def get_feature_flag(flag_name: str) -> bool:
    row = db.query("SELECT enabled FROM feature_flags WHERE name = %s", flag_name)
    return bool(row.enabled)

Snippet 7 — DRY-ed validation that needed to diverge (Python)¶

Difficulty: 🔴 Senior

Signup and profile-update both validate a password. They were merged into one validator. Then security tightened the signup policy.

MIN_LENGTH = 8

def validate_password(pw: str) -> None:
    if len(pw) < MIN_LENGTH:
        raise ValueError("Password too short")
    if not any(c.isdigit() for c in pw):
        raise ValueError("Password needs a digit")


# --- signup.py ---
def register(email: str, pw: str) -> User:
    validate_password(pw)
    return create_user(email, pw)


# --- profile.py ---
def change_password(user: User, old_pw: str, new_pw: str) -> None:
    if not verify(user, old_pw):
        raise ValueError("Wrong current password")
    validate_password(new_pw)
    store_password(user, new_pw)


# Security mandate (signup only): new accounts must use >= 12 chars and
# cannot reuse one of the user's last 5 passwords. An engineer edits the
# shared validator and threads a `user` argument through it:
def validate_password(pw: str, user: User | None = None) -> None:
    if len(pw) < 12:                                    # raised from 8 to 12
        raise ValueError("Password too short")
    if not any(c.isdigit() for c in pw):
        raise ValueError("Password needs a digit")
    if user is not None and pw in last_5_passwords(user):
        raise ValueError("Cannot reuse a recent password")

What's wrong?

def _basic_rules(pw: str, min_length: int) -> None:
    if len(pw) < min_length:
        raise ValueError("Password too short")
    if not any(c.isdigit() for c in pw):
        raise ValueError("Password needs a digit")

def validate_new_account_password(pw: str) -> None:
    _basic_rules(pw, min_length=12)            # signup policy

def validate_password_change(user: User, new_pw: str) -> None:
    _basic_rules(new_pw, min_length=8)         # change policy
    if new_pw in last_5_passwords(user):       # always checked here
        raise ValueError("Cannot reuse a recent password")

Snippet 8 — Premature base class forces a wrong default (Java)¶

Difficulty: 🔴 Senior

An abstract Report base class was designed up-front to capture "everything a report does." A new RealTimeReport extends it.

public abstract class Report {
    public final String render() {
        var data = fetch();
        var cached = cache(data);   // every report caches its fetched data
        return format(cached);
    }

    protected abstract List<Row> fetch();
    protected abstract String format(List<Row> rows);

    // Speculative: "all reports benefit from caching", so it's baked into render().
    protected List<Row> cache(List<Row> data) {
        ReportCache.put(getClass().getSimpleName(), data, Duration.ofMinutes(15));
        return ReportCache.get(getClass().getSimpleName());
    }
}

public class MonthlySalesReport extends Report {
    protected List<Row> fetch() { return salesDao.lastMonth(); }
    protected String format(List<Row> rows) { return Tables.render(rows); }
}

// New requirement: a live dashboard that must always show current data.
public class RealTimeReport extends Report {
    protected List<Row> fetch() { return metricsDao.now(); }
    protected String format(List<Row> rows) { return Tables.render(rows); }
}

What's wrong?

public abstract class Report {
    public final String render() {
        return format(fetch());        // no implicit caching
    }
    protected abstract List<Row> fetch();
    protected abstract String format(List<Row> rows);
}

// Caching becomes an explicit wrapper for the reports that want it:
public final class CachedReport extends Report {
    private final Report delegate;
    private final Duration ttl;
    public CachedReport(Report delegate, Duration ttl) { this.delegate = delegate; this.ttl = ttl; }
    protected List<Row> fetch() {
        return ReportCache.getOrCompute(delegate.getClass().getSimpleName(), ttl, delegate::fetch);
    }
    protected String format(List<Row> rows) { return delegate.format(rows); }
}

Snippet 9 — Over-general formatter swallows a timezone (Go)¶

Difficulty: 🔴 Senior

A single "format any timestamp" helper was extracted to avoid scattering layout strings. An audit-log caller and a user-profile caller share it.

package format

import "time"

// FormatTime renders a timestamp for display. One helper for the whole app,
// "so we never disagree on the format."
func FormatTime(t time.Time) string {
    return t.Format("2006-01-02 15:04:05")
}

// --- audit_log.go ---
// Audit entries are stored and compared in UTC.
func AuditLine(event string, at time.Time) string {
    return event + " at " + FormatTime(at.UTC())
}

// --- profile.go ---
// User profile shows the time the account was created, in the user's local zone.
func CreatedLine(u User) string {
    return "Joined " + FormatTime(u.CreatedAt) // CreatedAt carries a location
}

What's wrong?

// Audit: always UTC, always with an explicit offset so it round-trips.
func AuditLine(event string, at time.Time) string {
    return event + " at " + at.UTC().Format("2006-01-02T15:04:05Z07:00")
}

// Profile: user-local, but the offset is printed so it's unambiguous.
func CreatedLine(u User) string {
    return "Joined " + u.CreatedAt.Format("2006-01-02 15:04:05 MST")
}

Snippet 10 — Speculative event bus drops the only listener (Python)¶

Difficulty: 🔴 Senior

A simple "email the user after signup" need was implemented through a general-purpose event bus, "so we can add more handlers later."

from collections import defaultdict

class EventBus:
    def __init__(self):
        self._handlers: dict[str, list] = defaultdict(list)

    def subscribe(self, event: str, handler) -> None:
        self._handlers[event] = [handler]   # register the handler

    def publish(self, event: str, payload) -> None:
        for handler in self._handlers.get(event, []):
            handler(payload)


bus = EventBus()

# --- emails.py (loaded at startup) ---
bus.subscribe("user.signed_up", send_welcome_email)

# --- analytics.py (added a year later, also at startup) ---
bus.subscribe("user.signed_up", track_signup)

# --- signup.py ---
def register(email: str) -> User:
    user = create_user(email)
    bus.publish("user.signed_up", user)
    return user

What's wrong?

self._handlers[event] = [handler]   # ASSIGNS a new single-element list

def subscribe(self, event: str, handler) -> None:
    self._handlers[event].append(handler)   # accumulate handlers

def test_multiple_handlers_all_fire():
    bus, calls = EventBus(), []
    bus.subscribe("e", lambda p: calls.append("a"))
    bus.subscribe("e", lambda p: calls.append("b"))
    bus.publish("e", None)
    assert calls == ["a", "b"]   # would have failed and caught the bug

Snippet 11 — Generic retry wrapper retries a non-idempotent call (Go)¶

Difficulty: 🔴 Senior

A generic WithRetry helper was extracted so "any flaky operation" could be made resilient. A read endpoint used it; later, a payment charge reused it.

package resilience

import "time"

// WithRetry runs fn up to 3 times on error. "Use it for anything flaky."
func WithRetry(fn func() error) error {
    var err error
    for attempt := 0; attempt < 3; attempt++ {
        if err = fn(); err == nil {
            return nil
        }
        time.Sleep(time.Duration(attempt+1) * 100 * time.Millisecond)
    }
    return err
}

// --- inventory.go (original, safe) ---
func loadStock(sku string) (int, error) {
    var stock int
    err := WithRetry(func() error {
        var e error
        stock, e = inventoryAPI.Get(sku) // pure read, safe to repeat
        return e
    })
    return stock, err
}

// --- billing.go (added later) ---
func chargeCard(token string, cents int) error {
    return WithRetry(func() error {
        return paymentAPI.Charge(token, cents) // POST /charges
    })
}

What's wrong?

// Reads: retry freely.
func loadStock(sku string) (int, error) { /* WithRetry is fine here */ }

// Writes: retry only WITH an idempotency key the server honors.
func chargeCard(token string, cents int) error {
    key := newIdempotencyKey()
    return WithRetry(func() error {
        return paymentAPI.ChargeIdempotent(token, cents, key) // server dedupes
    })
}

Snippet 12 — Parameterized "do everything" method with a flag collision (Java)¶

Difficulty: 🔴 Senior

To avoid "duplicating" two similar export methods, they were merged into one parameterized method controlled by flags.

public class Exporter {

    // Was once two methods: exportForUser() and exportForArchive().
    // Merged "to stay DRY" into one configurable method.
    public byte[] export(
            List<Record> records,
            boolean includeHeader,
            boolean includePii,      // include personally identifiable fields
            boolean compress) {

        var rows = new ArrayList<String>();
        if (includeHeader) {
            rows.add(headerRow(includePii));
        }
        for (var r : records) {
            rows.add(toRow(r, includePii));
        }
        byte[] body = String.join("\n", rows).getBytes(UTF_8);
        return compress ? gzip(body) : body;
    }
}

// User-facing download: header, no PII (privacy), no compression.
exporter.export(records, true, false, false);

// Internal archive: no header, include PII, compressed.
exporter.export(records, false, true, true);

// New requirement six months later: a compliance export — header, NO PII,
// and it must be compressed. A new caller is added:
exporter.export(records, true, true, false);

What's wrong?

public class Exporter {
    public byte[] exportUserDownload(List<Record> records) {
        return render(records, /*header*/ true, /*pii*/ false, /*compress*/ false);
    }
    public byte[] exportArchive(List<Record> records) {
        return render(records, true_header(false), /*pii*/ true, /*compress*/ true);
    }
    public byte[] exportCompliance(List<Record> records) {
        return render(records, /*header*/ true, /*pii*/ false, /*compress*/ true);
    }

    private byte[] render(List<Record> records, boolean header, boolean pii, boolean compress) {
        // ... the shared formatting that was actually worth sharing ...
    }
}

Scorecard¶

Track how many you diagnosed without the answer. Each snippet is worth points by difficulty.

Scoring: 🟢 = 1 pt, 🟡 = 2 pts, 🔴 = 3 pts. Max = 24.

The meta-lesson across all twelve: a passing test suite does not validate an abstraction. Every bug here type-checked and (for the original caller) passed. The defect surfaced only when a second requirement met code that was generalized from a single example. Prefer duplication until the real pattern is proven by two or three concrete cases — that is what "emergent" design means.

Related Topics¶

• junior.md — the beginner-level definition of these emergent-design anti-patterns (speculative generality, premature abstraction, YAGNI, wrong DRY).
• tasks.md — hands-on exercises: take an over-engineered module and collapse it back to the simplest design that passes.
• Chapter README — the positive rules of Emergent Design (Kent Beck's four rules of simple design) that these snippets violate.
• Anti-Patterns — the broader catalogue of design smells, including over-engineering and gold-plating.
• Refactoring — the mechanical techniques (Inline Function, Inline Class, Collapse Hierarchy) used to undo a premature abstraction safely.