Abstraction Failures — Refactoring Practice¶

Category: Design Anti-Patterns → Abstraction Failures — the chosen abstraction fights the problem instead of fitting it. Covers (collectively): Golden Hammer · Inner-Platform Effect · Interface Bloat · Premature Abstraction

These are not "spot the smell" puzzles — find-bug.md does that. Here the code is abstracted in the wrong shape but already working, and your job is to bend it back toward the problem without changing behavior. The skill on display is the process, not just the destination:

1. Pin behavior first. Write a characterization test — a test that records what the code does now, bugs and quirks included. You are freezing behavior, not blessing it. When the whole point is performance, add a benchmark alongside, so "faster" is a measured claim, not a hope.
2. Take small, reversible steps. One named refactoring at a time (Inline Class, Extract Interface, Replace Conditional with Lookup Table, …), tests green after each, commit.
3. Separate structural from behavioral commits. A refactor must preserve behavior; a measured perf win is allowed precisely because the characterization test proves output is unchanged while the benchmark proves the cost dropped.

Abstraction failures are subtle because the code runs. The Golden Hammer works — slowly. The Inner-Platform rule engine evaluates rules — unmaintainably. The bloated interface compiles — until an implementer throws UnsupportedOperationException. The premature abstraction has exactly one subclass — forever. Each worked solution names the canonical refactoring moves (Fowler's Refactoring, Feathers' Working Effectively with Legacy Code) so you build the vocabulary, not just the instinct.

One counter-case matters. Not every abstraction is wrong. Exercise 11 hands you a "premature-looking" abstraction that is actually justified — and the correct refactoring is to keep it and document why. Knowing when not to inline is as important as knowing how.

How to use this file: read the "Before" code, write down the move sequence yourself (and, for the perf ones, predict the speedup) before expanding the solution, then compare.

Table of Contents¶

Exercise 1 — Regex where a substring will do¶

Anti-pattern: Golden Hammer (regex for everything). Goal: replace a compiled regex used for a literal prefix/suffix check with plain string operations and show the speedup. Constraints: identical boolean results for every input; this is a hot path, so prove the win with a benchmark.

// Before — a regex object built to answer "does this look like an image filename?"
var imageRe = regexp.MustCompile(`(?i)\.(jpg|jpeg|png|gif)$`)

func IsImage(name string) bool {
    return imageRe.MatchString(name)
}

// After — plain suffix check over a fixed set.
var imageExts = []string{".jpg", ".jpeg", ".png", ".gif"}

func IsImage(name string) bool {
    lower := strings.ToLower(name)
    for _, ext := range imageExts {
        if strings.HasSuffix(lower, ext) {
            return true
        }
    }
    return false
}

func BenchmarkIsImageRegex(b *testing.B) {
    for i := 0; i < b.N; i++ { _ = imageRe.MatchString("photo_2026.JPEG") }
}
func BenchmarkIsImageSuffix(b *testing.B) {
    for i := 0; i < b.N; i++ { _ = IsImage("photo_2026.JPEG") }
}

BenchmarkIsImageRegex-8     6_000_000   ~195 ns/op   16 B/op   1 allocs/op
BenchmarkIsImageSuffix-8   80_000_000    ~14 ns/op    0 B/op   0 allocs/op

Exercise 2 — Map used as a tiny lookup¶

Anti-pattern: Golden Hammer (HashMap as the universal collection). Goal: replace a heap-allocating HashMap rebuilt on every call with a flat array/slice lookup over a tiny, fixed key space. Constraints: same return value per input; prove the allocation and time win.

// Before — a 7-entry map rebuilt on every call to translate a weekday index to a name.
String dayName(int dow) {      // dow in 0..6
    Map<Integer, String> names = new HashMap<>();
    names.put(0, "Sun"); names.put(1, "Mon"); names.put(2, "Tue");
    names.put(3, "Wed"); names.put(4, "Thu"); names.put(5, "Fri");
    names.put(6, "Sat");
    String n = names.get(dow);
    if (n == null) throw new IllegalArgumentException("bad dow: " + dow);
    return n;
}

// After — a hoisted, immutable array; lookup is one bounds check + one load.
private static final String[] DAY_NAMES =
    { "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" };

String dayName(int dow) {
    if (dow < 0 || dow >= DAY_NAMES.length)
        throw new IllegalArgumentException("bad dow: " + dow);
    return DAY_NAMES[dow];
}

Benchmark              Mode  Cnt   Score    Error  Units
dayNameMapPerCall     avgt    5   58.3 ±  2.1  ns/op   (allocates a HashMap + 7 entries each call)
dayNameArray          avgt    5    1.6 ±  0.1  ns/op   (zero allocation)

Exercise 3 — ORM N+1 → one bulk query¶

Anti-pattern: Golden Hammer (the ORM is the only data tool). Goal: replace a per-row lazy-load loop (the classic N+1) with a single bulk query. Constraints: the returned data must be identical; prove the query-count and latency win.

# Before — one query for orders, then one query PER order for its customer (N+1).
def order_summaries(session):
    orders = session.query(Order).all()              # 1 query
    out = []
    for o in orders:
        cust = session.query(Customer).get(o.customer_id)  # N queries (one per order)
        out.append({"order_id": o.id, "customer": cust.name, "total": o.total})
    return out

# After — two queries total, regardless of order count.
def order_summaries(session):
    orders = session.query(Order).all()                       # 1 query
    cust_ids = {o.customer_id for o in orders}
    customers = session.query(Customer).filter(Customer.id.in_(cust_ids)).all()  # 1 query
    name_by_id = {c.id: c.name for c in customers}
    return [
        {"order_id": o.id, "customer": name_by_id[o.customer_id], "total": o.total}
        for o in orders
    ]

                         queries   wall time (1k orders, 1ms RTT)
Before (N+1)             1 + 1000   ~1.0 s   (latency dominated by round trips)
After (bulk IN)          2          ~3 ms

Exercise 4 — Inline a one-implementation interface¶

Anti-pattern: Premature Abstraction (speculative interface). Goal: remove an interface + factory introduced "in case we need another backend," when there is exactly one implementation and no second one in sight. Constraints: no behavior change; callers may be updated.

// Before — an interface, a factory, and a single concrete type. No second impl, ever.
type Clock interface {
    Now() time.Time
}

type systemClock struct{}

func (systemClock) Now() time.Time { return time.Now() }

func NewClock() Clock { return systemClock{} }

// usage scattered through the package:
//   c := NewClock()
//   t := c.Now()

// After — the abstraction earned nothing, so it's gone.
func Now() time.Time { return time.Now() }

// usage:
//   t := Now()

Exercise 5 — Collapse a one-case Strategy¶

Anti-pattern: Premature Abstraction (Strategy pattern with one strategy). Goal: inline a Strategy hierarchy that has exactly one concrete strategy and a registry that only ever holds it. Constraints: same computed discount; callers may change.

# Before — a Strategy interface, one strategy, and a "selector" that always returns it.
from abc import ABC, abstractmethod

class DiscountStrategy(ABC):
    @abstractmethod
    def apply(self, total: float) -> float: ...

class StandardDiscount(DiscountStrategy):
    def apply(self, total: float) -> float:
        return total * 0.9 if total > 100 else total

def select_strategy(_customer) -> DiscountStrategy:
    return StandardDiscount()          # never returns anything else

def final_price(customer, total):
    strategy = select_strategy(customer)
    return round(strategy.apply(total), 2)

# After — one rule, one function.
def final_price(customer, total):
    discounted = total * 0.9 if total > 100 else total
    return round(discounted, 2)

Exercise 6 — Segregate a bloated interface¶

Anti-pattern: Interface Bloat. Goal: split a fat interface that no implementer fully needs into small role interfaces (Interface Segregation Principle). Constraints: every existing call site keeps working; implementers stop being forced to satisfy methods they don't use.

// Before — a fat "repository" no caller uses in full; some impls fake half of it.
interface UserStore {
    User findById(long id);
    List<User> findAll();
    void save(User u);
    void delete(long id);
    void bulkImport(InputStream csv);     // only the admin importer needs this
    byte[] exportCsv();                   // only the reporting job needs this
    void reindexSearch();                 // only the search subsystem needs this
    Stats computeStats();                 // only the dashboard needs this
}

// After — role interfaces; clients depend on the slice they use.
interface UserReader {
    User findById(long id);
    List<User> findAll();
}
interface UserWriter {
    void save(User u);
    void delete(long id);
}
interface UserBulkIo {
    void bulkImport(InputStream csv);
    byte[] exportCsv();
}
interface UserAnalytics {
    void reindexSearch();
    Stats computeStats();
}

// One concrete class can still satisfy all roles:
class JdbcUserStore implements UserReader, UserWriter, UserBulkIo, UserAnalytics { /* ... */ }

// Consumers narrow to a role:
class ProfileHandler {
    private final UserReader users;            // can't even see bulkImport / exportCsv
    ProfileHandler(UserReader users) { this.users = users; }
}

Exercise 7 — Kill the UnsupportedOperationException¶

Anti-pattern: Interface Bloat (the smoking gun: implementers throw "not supported"). Goal: an interface so wide that a real implementer can't honor it and throws at runtime — segregate so the type system, not an exception, expresses capability. Constraints: callers that only use supported methods are unaffected; the runtime throw disappears.

// Before — a read-only view is forced to "implement" mutation, so it panics.
type Collection interface {
    Get(i int) (string, bool)
    Len() int
    Add(s string)
    Remove(i int)
}

type immutableView struct{ data []string }

func (v immutableView) Get(i int) (string, bool) {
    if i < 0 || i >= len(v.data) { return "", false }
    return v.data[i], true
}
func (v immutableView) Len() int        { return len(v.data) }
func (v immutableView) Add(s string)    { panic("immutable: Add not supported") }   // bloat tell
func (v immutableView) Remove(i int)    { panic("immutable: Remove not supported") } // bloat tell

// After — capability is in the type; the panic is unrepresentable.
type Reader interface {
    Get(i int) (string, bool)
    Len() int
}

type Mutator interface {
    Add(s string)
    Remove(i int)
}

// A full collection composes both roles.
type MutableCollection interface {
    Reader
    Mutator
}

type immutableView struct{ data []string }

func (v immutableView) Get(i int) (string, bool) {
    if i < 0 || i >= len(v.data) { return "", false }
    return v.data[i], true
}
func (v immutableView) Len() int { return len(v.data) }
// No Add / Remove — and that's the point: it simply isn't a Mutator.

// A function that mutates demands the capability in its signature:
func appendAll(m Mutator, items []string) {
    for _, it := range items { m.Add(it) }
}
// appendAll(immutableView{...}, ...) // ← does not compile

Exercise 8 — Retire a config-driven mini-language¶

Anti-pattern: Inner-Platform Effect. Goal: replace a tiny home-grown expression language (parsed from config strings at runtime) with plain, tested host code. Constraints: the rules currently in config must produce identical decisions; new rules become code changes (accepted trade-off).

# Before — a string "DSL" interpreted at runtime to decide free shipping.
# config: "total > 50 AND country == US OR vip == true"
def eligible_for_free_shipping(order, rule_string):
    # a hand-rolled tokenizer + evaluator (~80 lines) that supports
    # ==, >, <, AND, OR over a fixed set of order attributes.
    tokens = tokenize(rule_string)
    return evaluate(tokens, {
        "total": order.total, "country": order.country, "vip": order.vip,
    })

# After — rules are ordinary, tested functions; the interpreter is deleted.
def standard_free_shipping(order) -> bool:
    return (order.total > 50 and order.country == "US") or order.vip

# If the deployment really needs to choose among a few known rules:
RULES = {
    "standard": standard_free_shipping,
    "eu_promo": lambda o: o.total > 30 or o.vip,
}

def eligible_for_free_shipping(order, rule_name="standard") -> bool:
    return RULES[rule_name](order)

Exercise 9 — Rule engine → plain tested functions¶

Anti-pattern: Inner-Platform Effect (a data-driven "rule engine"). Goal: migrate a generic condition/action rule engine (rules stored as data, dispatched by a loop) back to explicit, polymorphic code. Constraints: the same actions fire for the same inputs; the migration is incremental.

// Before — a generic engine: rules are rows; the engine is a soup of ifs over "operators".
class Rule {
    String field; String op; Object value; String action;   // stringly-typed everything
}
class RuleEngine {
    void run(Map<String,Object> facts, List<Rule> rules, Actions actions) {
        for (Rule r : rules) {
            Object f = facts.get(r.field);
            boolean match;
            if (r.op.equals("eq"))      match = f.equals(r.value);
            else if (r.op.equals("gt")) match = ((Number) f).doubleValue() > ((Number) r.value).doubleValue();
            else if (r.op.equals("lt")) match = ((Number) f).doubleValue() < ((Number) r.value).doubleValue();
            else throw new IllegalStateException("unknown op " + r.op);
            if (match) actions.fire(r.action);   // action also stringly dispatched
        }
    }
}

// After — each rule is a typed, tested object; no interpreter, no stringly-typed dispatch.
interface Rule {
    boolean matches(Facts f);
    void fire(Actions a);
}

final class HighValueRule implements Rule {
    public boolean matches(Facts f) { return f.orderTotal() > 1000; }
    public void fire(Actions a)     { a.flagForReview(); }
}

final class VipRule implements Rule {
    public boolean matches(Facts f) { return f.isVip(); }
    public void fire(Actions a)     { a.applyVipPerks(); }
}

class Rules {
    private final List<Rule> rules = List.of(new HighValueRule(), new VipRule());
    void run(Facts f, Actions a) {
        for (Rule r : rules) if (r.matches(f)) r.fire(a);
    }
}

Exercise 10 — In-DB scripting → host code¶

Anti-pattern: Inner-Platform Effect + Golden Hammer. Goal: move business logic encoded as interpreted strings inside database rows (a "scripting" column the app evals) out into versioned host code, and fix the row-by-row access while you're there. Constraints: same computed fees; same totals.

# Before — each fee rule is a Python expression stored in a DB column and eval'd per row.
# table fee_rules(id, name, expr)  e.g. expr = "amount * 0.029 + 0.30"
def total_fees(session, txns):
    rules = session.query(FeeRule).all()          # the "scripts"
    total = 0.0
    for t in txns:
        for r in rules:
            fee = eval(r.expr, {"amount": t.amount})   # interpreting DB-stored code (!!)
            total += fee
    return round(total, 2)

# After — fee rules are versioned functions; eval and the inner loop are gone.
def standard_processing_fee(amount: float) -> float:
    return amount * 0.029 + 0.30

FEE_RULES = [standard_processing_fee]   # add named, tested functions here

def total_fees(txns) -> float:
    total = sum(rule(t.amount) for t in txns for rule in FEE_RULES)
    return round(total, 2)

Exercise 11 — The abstraction you KEEP (counter-case)¶

Anti-pattern: Premature Abstraction — but here the abstraction is justified. Goal: practice recognizing a legitimate seam and not inlining it. The discipline is knowing when to stop. Constraints: behavior unchanged — because you change nothing structural except adding a clarifying comment/test.

// "Before" — looks like Exercise 4: an interface with one production implementation.
type PaymentGateway interface {
    Charge(amountCents int64, token string) (chargeID string, err error)
}

type stripeGateway struct{ apiKey string }

func (g stripeGateway) Charge(amountCents int64, token string) (string, error) {
    return stripe.Charge(g.apiKey, amountCents, token)   // real network call to Stripe
}

// And in tests:
type fakeGateway struct{ lastAmount int64 }
func (f *fakeGateway) Charge(amountCents int64, token string) (string, error) {
    f.lastAmount = amountCents
    return "test_charge_123", nil
}

func TestCheckoutChargesCorrectAmount(t *testing.T) {
    fake := &fakeGateway{}
    checkout(fake, cart)                       // ← the seam earns its keep
    if fake.lastAmount != 4200 { t.Fatal("wrong amount") }
}

// After — unchanged code, plus a comment that states the seam's reason.
// PaymentGateway is an intentional seam: it is faked in tests to avoid
// real Stripe charges (network + money side effects). Do NOT inline —
// the fake implementation is the justifying second case (see gateway_test.go).
type PaymentGateway interface {
    Charge(amountCents int64, token string) (chargeID string, err error)
}

Exercise 12 — Plugin instead of a DSL¶

Anti-pattern: Inner-Platform Effect. Goal: the requirement is real runtime extensibility — but instead of a home-grown DSL (Ex. 8/9's cure doesn't apply when configurability is genuinely needed), expose a constrained plugin API in the host language. Constraints: existing built-in behaviors unchanged; third parties can add behaviors without editing core.

# Before — a half-built DSL grown to support "custom" export formats at runtime.
# Users write strings like: "FIELD name | UPPER | PAD 10 | FIELD price | MULT 1.1"
# parsed and interpreted by ~150 lines of pipeline-language code.
def export_row(row, pipeline_string):
    ops = parse_pipeline(pipeline_string)      # custom tokenizer + op table
    return run_pipeline(ops, row)              # custom interpreter

# After — a registry of host-language plugins; no parser, no interpreter.
from typing import Protocol

class Formatter(Protocol):
    def format(self, row: dict) -> str: ...

class NameUpperFormatter:
    def format(self, row: dict) -> str:
        return row["name"].upper().ljust(10)

_REGISTRY: dict[str, Formatter] = {}

def register(name: str, formatter: Formatter) -> None:
    _REGISTRY[name] = formatter

register("name_upper", NameUpperFormatter())   # built-in
# third parties:  register("my_format", MyFormatter())  — real code, their own tests

def export_row(row: dict, formatter_name: str) -> str:
    return _REGISTRY[formatter_name].format(row)

Exercise 13 — The full combo cleanup¶

Anti-pattern: all four at once. Goal: one component exhibiting a Golden Hammer (regex + per-call map), Interface Bloat, a tiny Inner-Platform rule string, and a Premature Abstraction. Tackle them in a safe order. Constraints: preserve the routing decision and the audit string; one anti-pattern per commit.

// Before — a notification router with a bit of every abstraction failure.
interface Channel {                                  // BLOAT: nobody implements all of this
    void send(String to, String body);
    void sendBulk(List<String> to, String body);     // only the newsletter job uses this
    byte[] renderPreview(String body);                // only the admin UI uses this
    Stats deliveryStats();                            // only the dashboard uses this
}

abstract class AbstractRouter {                       // PREMATURE: one subclass, ever
    abstract Channel pick(String userPref);
}

class Router extends AbstractRouter {
    Channel pick(String userPref) {
        // GOLDEN HAMMER 1: regex to test a fixed literal
        if (Pattern.matches("sms", userPref)) return sms;
        // GOLDEN HAMMER 2: a map rebuilt every call for 2 keys
        Map<String,Channel> m = new HashMap<>();
        m.put("email", email); m.put("push", push);
        // INNER-PLATFORM: a stringly "rule" parsed inline
        if (userPref.startsWith("rule:")) {
            String[] kv = userPref.substring(5).split("=");  // "channel=email"
            return m.get(kv[1]);
        }
        return m.getOrDefault(userPref, email);
    }
}

// After — flat dispatch over a hoisted table; narrow dependency; no interpreter.
interface MessageSender {           // the only role Router needs
    void send(String to, String body);
}
// (sendBulk / renderPreview / deliveryStats live on BulkSender / Previewer /
//  StatsSource — implemented by the concrete channels, used by their real clients.)

class Router {
    private static final Set<String> KNOWN = Set.of("sms", "email", "push");
    private final Map<String, MessageSender> channels;   // injected once, not rebuilt

    Router(Map<String, MessageSender> channels) { this.channels = channels; }

    MessageSender pick(String userPref) {
        String key = userPref.startsWith("rule:")        // normalize legacy "rule:channel=x"
            ? userPref.substring(5).split("=")[1]
            : userPref;
        return KNOWN.contains(key) ? channels.get(key) : channels.get("email");
    }
}

Refactoring discipline — the recap¶

Every exercise above runs the same loop. Internalize it and the specific moves become mechanical:

green  →  one named refactoring  →  green  →  commit  →  repeat
          (a MEASURED perf win is allowed: characterization proves output,
           benchmark proves cost — they are separate, recorded claims)

• Characterize before you change. A test that pins current behavior (quirks and all) is the seatbelt. For the perf exercises (1, 2, 3, 10) add a benchmark so "faster" is a number you can defend, and an assertion on the resource that was being wasted (query count in Ex. 3, allocations in Ex. 2) so the regression can't creep back.
• Match the tool to the problem (cure for Golden Hammer). Regex is for patterns, not fixed prefixes; a hash map is for sparse keys, not a dense 0..n; an ORM's per-object navigation is for single objects, not sets. The fix is almost always "use the smaller, more specific tool," and it's almost always faster.
• Don't rebuild the platform inside the platform (cure for Inner-Platform Effect). If you're writing a tokenizer, an operator table, or an eval of stored strings, you're reimplementing your host language — badly and insecurely. Push logic into real, tested, version-controlled code. When extensibility is a genuine requirement, expose a constrained plugin API, not a DSL (Ex. 12).
• Segregate by client, not by convenience (cure for Interface Bloat). When an implementer throws "not supported," the interface is a union of capabilities that should be separate role interfaces. Split by who uses what together; let the type system, not a runtime exception, express capability.
• Honor the Rule of Three — both directions (cure for Premature Abstraction). Extract an abstraction only when a real case needs it; inline one that has a single destination. But count test doubles and real boundaries as cases — the one abstraction you keep (Ex. 11) is as important as the ones you inline.
• Name the move. "Replace Algorithm," "Replace Data Structure," "Inline Class," "Remove Speculative Generality," "Extract Interface," "Replace Conditional with Polymorphism," "Replace Interpreter with Code." A named move is a known-safe, often IDE-automatable transformation — not an improvisation.
• Separate structural from behavioral commits. A refactor preserves behavior; a perf win is allowed because the characterization test proves output is unchanged. Capability tightenings (the removed panic in Ex. 7, the impossible-to-construct illegal call in the bloat fixes) get called out in the PR so reviewers expect them.

Related Topics¶

• tasks.md — guided exercises building these moves from scratch.
• find-bug.md — the spotting counterpart: identify the abstraction failure, don't fix it.
• junior.md · middle.md · senior.md · professional.md — recognize → countermove → migrate at scale → perf/testability implications.
• Refactoring → Refactoring Techniques — the mechanical catalog for every move named above (Inline Class, Extract Interface, Replace Algorithm).
• Clean Code → Classes — the Interface Segregation Principle and cohesion, the target state for Exercises 6–7.
• Design Patterns → Structural — Adapter/Facade for narrowing wide interfaces; the positive counterparts to bloat.
• Design Patterns → Behavioral — Strategy done right (extracted at the Rule of Three), the counterpart to Exercises 5 and 9.