Abstraction & Information Hiding — Find the Bug¶

12 buggy snippets where a leaky or shallow abstraction causes a real bug. A design decision escaped the one module that should have owned it, so two pieces of code now disagree — or a hidden detail surfaced where the interface promised it wouldn't. Find the bug, then trace it back to the leak. The fix is almost always to deepen the module: hide the decision in one place and stop making callers know about it.

Table of Contents¶

1. Snippet 1 — Duplicated buffer size in two modules (Go)
2. Snippet 2 — Exposed mutable slice breaks an invariant (Go)
3. Snippet 3 — Lazy-load leaks the transaction boundary (Python)
4. Snippet 4 — Pass-through method forgot a parameter (Java)
5. Snippet 5 — Shallow wrapper swallows the error below (Go)
6. Snippet 6 — Temporal decomposition assumes unset state (Python)
7. Snippet 7 — Caller depends on undocumented iteration order (Java)
8. Snippet 8 — "General" config flag with an untested combination (Python)
9. Snippet 9 — Index base duplicated across the boundary (Go)
10. Snippet 10 — Iterator invalidated by a mutation the interface allowed (Java)
11. Snippet 11 — Leaked enum default surfaces in a new branch (Python)
12. Snippet 12 — Date format decided in two places (Go)
13. Scorecard
14. Related Topics

How to Use¶

Read each snippet and decide where the bug is and why weak information hiding let it happen. The trigger is almost never a typo — it is a design decision that lives in two places, or a detail the interface failed to hide. Then open the answer.

A leak follows a predictable shape:

Score yourself with the Scorecard. Each snippet names the leak, the bug it caused, and the deep-module fix that makes the bug structurally impossible — not merely patched.

Snippet 1 — Duplicated buffer size in two modules (Go)¶

Difficulty: Easy

// package framing — owns the wire protocol
package framing

func Encode(payload []byte) []byte {
    frame := make([]byte, 0, 4+len(payload))
    frame = append(frame, byte(len(payload)>>24), byte(len(payload)>>16),
        byte(len(payload)>>8), byte(len(payload)))
    return append(frame, payload...)
}

// package reader — in a different file, written later
package reader

const headerSize = 2 // length prefix is 2 bytes

func ReadFrame(conn net.Conn) ([]byte, error) {
    header := make([]byte, headerSize)
    if _, err := io.ReadFull(conn, header); err != nil {
        return nil, err
    }
    length := int(header[0])<<8 | int(header[1])
    payload := make([]byte, length)
    _, err := io.ReadFull(conn, payload)
    return payload, err
}

What's wrong?

package framing

const prefixLen = 4

func Encode(payload []byte) []byte {
    frame := make([]byte, prefixLen+len(payload))
    binary.BigEndian.PutUint32(frame, uint32(len(payload)))
    copy(frame[prefixLen:], payload)
    return frame
}

func Decode(conn io.Reader) ([]byte, error) {
    header := make([]byte, prefixLen)
    if _, err := io.ReadFull(conn, header); err != nil {
        return nil, err
    }
    payload := make([]byte, binary.BigEndian.Uint32(header))
    _, err := io.ReadFull(conn, payload)
    return payload, err
}

Snippet 2 — Exposed mutable slice breaks an invariant (Go)¶

Difficulty: Easy

type Histogram struct {
    buckets []int
    total   int
}

func NewHistogram(n int) *Histogram {
    return &Histogram{buckets: make([]int, n)}
}

func (h *Histogram) Add(bucket int) {
    h.buckets[bucket]++
    h.total++
}

// Buckets exposes the raw counts for rendering.
func (h *Histogram) Buckets() []int {
    return h.buckets
}

func (h *Histogram) Mean() float64 {
    sum := 0
    for i, c := range h.buckets {
        sum += i * c
    }
    return float64(sum) / float64(h.total)
}

// Caller, in a dashboard module:
func render(h *Histogram) {
    b := h.Buckets()
    b[0] = 0 // "hide the noisy zero bucket from the chart"
}

What's wrong?

Where is the bug?

// Buckets returns a snapshot the caller may freely mutate.
func (h *Histogram) Buckets() []int {
    out := make([]int, len(h.buckets))
    copy(out, h.buckets)
    return out
}

// Or, cheaper and intent-revealing, expose only what callers need:
func (h *Histogram) Count(bucket int) int { return h.buckets[bucket] }
func (h *Histogram) Len() int             { return len(h.buckets) }

Snippet 3 — Lazy-load leaks the transaction boundary (Python)¶

Difficulty: Medium

# repository.py
class OrderRepository:
    def __init__(self, session_factory):
        self._session_factory = session_factory

    def find(self, order_id):
        with self._session_factory() as session:
            return session.query(Order).get(order_id)


# service.py
class InvoiceService:
    def __init__(self, repo):
        self._repo = repo

    def total_with_lines(self, order_id):
        order = self._repo.find(order_id)
        total = Decimal("0")
        for line in order.lines:          # relationship, lazy-loaded
            total += line.unit_price * line.quantity
        return total

What's wrong?

class OrderRepository:
    def find(self, order_id):
        with self._session_factory() as session:
            order = (
                session.query(Order)
                .options(joinedload(Order.lines))  # load lines inside the session
                .get(order_id)
            )
            # Return a plain value object — no live-session dependency leaks out.
            return OrderView(
                id=order.id,
                lines=[LineView(l.unit_price, l.quantity) for l in order.lines],
            )

Snippet 4 — Pass-through method forgot a parameter (Java)¶

Difficulty: Medium

public class CachingUserClient {
    private final UserApi delegate;
    private final Cache<String, User> cache;

    public User getUser(String userId, boolean includeArchived) {
        User cached = cache.getIfPresent(userId);
        if (cached != null) {
            return cached;
        }
        // Pass-through to the real client.
        User user = delegate.fetchUser(userId);   // (?)
        cache.put(userId, user);
        return user;
    }
}

// UserApi:
public interface UserApi {
    User fetchUser(String userId);
    User fetchUser(String userId, boolean includeArchived);
}

What's wrong?

public class CachingUserClient {
    private final UserApi delegate;
    private final Cache<CacheKey, User> cache;

    public User getUser(String userId, boolean includeArchived) {
        CacheKey key = new CacheKey(userId, includeArchived); // key reflects all inputs
        return cache.get(key, k -> delegate.fetchUser(k.userId(), k.includeArchived()));
    }
}

// And drop the convenience overload from UserApi — one method, one behavior:
public interface UserApi {
    User fetchUser(String userId, boolean includeArchived);
}

Snippet 5 — Shallow wrapper swallows the error below (Go)¶

Difficulty: Medium

type ConfigStore struct {
    db *sql.DB
}

// Get returns the value for a key, or "" if not set.
func (c *ConfigStore) Get(key string) string {
    var value string
    row := c.db.QueryRow("SELECT value FROM config WHERE key = $1", key)
    row.Scan(&value)
    return value
}

// Caller:
func startServer(cfg *ConfigStore) {
    maxConns := cfg.Get("max_connections")
    n, _ := strconv.Atoi(maxConns)
    pool := newPool(n)
    // ...
}

What's wrong?

var ErrNotSet = errors.New("config key not set")

func (c *ConfigStore) Get(key string) (string, error) {
    var value string
    err := c.db.QueryRow("SELECT value FROM config WHERE key = $1", key).Scan(&value)
    if errors.Is(err, sql.ErrNoRows) {
        return "", ErrNotSet
    }
    if err != nil {
        return "", fmt.Errorf("config get %q: %w", key, err) // real failure surfaces
    }
    return value, nil
}

// Caller can now fail fast on a dead DB and apply a default only on ErrNotSet.
func startServer(cfg *ConfigStore) error {
    raw, err := cfg.Get("max_connections")
    if errors.Is(err, ErrNotSet) {
        raw = "50"
    } else if err != nil {
        return fmt.Errorf("startup: %w", err) // do NOT boot with a guessed value
    }
    n, err := strconv.Atoi(raw)
    if err != nil {
        return fmt.Errorf("max_connections not an int: %w", err)
    }
    pool := newPool(n)
    _ = pool
    return nil
}

Snippet 6 — Temporal decomposition assumes unset state (Python)¶

Difficulty: Medium

class ReportBuilder:
    def __init__(self, raw_rows):
        self.raw_rows = raw_rows
        self.rows = None
        self.totals = None

    def step1_clean(self):
        self.rows = [r for r in self.raw_rows if r["amount"] is not None]

    def step2_aggregate(self):
        by_region = defaultdict(Decimal)
        for r in self.rows:
            by_region[r["region"]] += Decimal(str(r["amount"]))
        self.totals = dict(by_region)

    def step3_format(self):
        return "\n".join(f"{region}: {amount:.2f}"
                         for region, amount in self.totals.items())


# Caller, refactored last week to support an "already clean" fast path:
def build_report(rows, prevalidated=False):
    b = ReportBuilder(rows)
    if not prevalidated:
        b.step1_clean()
    b.step2_aggregate()
    return b.step3_format()

What's wrong?

def clean(raw_rows):
    return [r for r in raw_rows if r["amount"] is not None]

def aggregate(rows):
    by_region = defaultdict(Decimal)
    for r in rows:
        by_region[r["region"]] += Decimal(str(r["amount"]))
    return dict(by_region)

def format_report(totals):
    return "\n".join(f"{region}: {amount:.2f}" for region, amount in totals.items())

def build_report(rows, prevalidated=False):
    clean_rows = rows if prevalidated else clean(rows)  # the data dependency is now explicit
    return format_report(aggregate(clean_rows))

Snippet 7 — Caller depends on undocumented iteration order (Java)¶

Difficulty: Hard

public class TaxRuleEngine {
    private final Map<String, TaxRule> rules = new HashMap<>();

    public void register(String code, TaxRule rule) {
        rules.put(code, rule);
    }

    // Returns every rule; callers apply them in the returned order.
    public Collection<TaxRule> allRules() {
        return rules.values();
    }
}

// Caller:
public Money applyTaxes(Money base, TaxRuleEngine engine) {
    Money result = base;
    for (TaxRule rule : engine.allRules()) {
        result = rule.apply(result);   // order-sensitive: VAT before surcharge
    }
    return result;
}

What's wrong?

public class TaxRuleEngine {
    // Each rule declares its position; the engine owns ordering.
    private final List<TaxRule> rules = new ArrayList<>();

    public void register(TaxRule rule) {
        rules.add(rule);
        rules.sort(Comparator.comparingInt(TaxRule::priority)); // explicit, total order
    }

    /** Rules in guaranteed application order (ascending priority). */
    public List<TaxRule> orderedRules() {
        return List.copyOf(rules); // immutable snapshot; no internal leak
    }
}

Snippet 8 — "General" config flag with an untested combination (Python)¶

Difficulty: Hard

class CsvExporter:
    def __init__(self, delimiter=",", quote_all=False, escape_char=None,
                 line_terminator="\n", trim_whitespace=False):
        self.delimiter = delimiter
        self.quote_all = quote_all
        self.escape_char = escape_char
        self.line_terminator = line_terminator
        self.trim_whitespace = trim_whitespace

    def _field(self, value):
        s = str(value)
        if self.trim_whitespace:
            s = s.strip()
        if self.escape_char:
            s = s.replace(self.delimiter, self.escape_char + self.delimiter)
        if self.quote_all:
            s = f'"{s}"'
        return s

    def row(self, values):
        return self.line_terminator.join([])  # placeholder
        # return self.delimiter.join(self._field(v) for v in values) + self.line_terminator

Assume row is the commented line. A user configures CsvExporter(quote_all=True, escape_char="\\") to be "extra safe."

What's wrong?

from enum import Enum

class Quoting(Enum):
    MINIMAL = "minimal"   # RFC 4180: quote only when needed
    ALL = "all"           # quote every field
    ESCAPED = "escaped"   # backslash-escape, no quotes

class CsvExporter:
    def __init__(self, delimiter=",", quoting=Quoting.MINIMAL,
                 line_terminator="\n", trim_whitespace=False):
        self.delimiter = delimiter
        self.quoting = quoting
        self.line_terminator = line_terminator
        self.trim_whitespace = trim_whitespace

    def _field(self, value):
        s = str(value).strip() if self.trim_whitespace else str(value)
        needs_quote = self.delimiter in s or '"' in s or "\n" in s
        if self.quoting is Quoting.ALL or (self.quoting is Quoting.MINIMAL and needs_quote):
            return '"' + s.replace('"', '""') + '"'   # RFC 4180 doubling
        if self.quoting is Quoting.ESCAPED:
            return s.replace("\\", "\\\\").replace(self.delimiter, "\\" + self.delimiter)
        return s

Snippet 9 — Index base duplicated across the boundary (Go)¶

Difficulty: Medium

// package sheet — models a spreadsheet; columns are 0-indexed internally.
package sheet

type Sheet struct {
    cells [][]string
}

func (s *Sheet) Set(row, col int, v string) { s.cells[row][col] = v }
func (s *Sheet) Get(row, col int) string    { return s.cells[row][col] }

// package importer — maps a user's column letters to indices, written separately.
package importer

// Users type columns as A=1, B=2, ... (1-based, matching the UI label).
func columnIndex(letter string) int {
    return int(letter[0]-'A') + 1
}

func Import(s *sheet.Sheet, records []Record) {
    for r, rec := range records {
        s.Set(r, columnIndex("A"), rec.Name)   // column A
        s.Set(r, columnIndex("B"), rec.Email)  // column B
    }
}

What's wrong?

package sheet

// Col is a column reference. Construct it through the package so the base is fixed here.
type Col int

// ColFromLetter is the ONLY supported way to name a column; the 0/1 decision lives here.
func ColFromLetter(letter byte) Col { return Col(letter - 'A') } // A -> 0, owned by sheet

func (s *Sheet) Set(row int, col Col, v string) { s.cells[row][int(col)] = v }

// importer now cannot invent its own base — it must go through sheet.
func Import(s *sheet.Sheet, records []Record) {
    for r, rec := range records {
        s.Set(r, sheet.ColFromLetter('A'), rec.Name)
        s.Set(r, sheet.ColFromLetter('B'), rec.Email)
    }
}

Snippet 10 — Iterator invalidated by a mutation the interface allowed (Java)¶

Difficulty: Hard

public class SessionRegistry {
    private final Map<String, Session> sessions = new ConcurrentHashMap<>();

    public void add(Session s)          { sessions.put(s.id(), s); }
    public void remove(String id)       { sessions.remove(id); }

    // Sweep expired sessions.
    public void evictExpired(Instant now) {
        for (Session s : sessions.values()) {
            if (s.expiresAt().isBefore(now)) {
                remove(s.id());                 // (?)
                listener.onEvicted(s);          // may re-enter the registry
            }
        }
    }
}

listener.onEvicted is a user-supplied callback that, in one deployment, calls registry.add(...) to spawn a replacement session.

What's wrong?

public void evictExpired(Instant now) {
    // 1) Compute the victims against a stable snapshot — no mutation during scan.
    List<Session> expired = sessions.values().stream()
            .filter(s -> s.expiresAt().isBefore(now))
            .toList();

    // 2) Apply structural changes.
    for (Session s : expired) {
        sessions.remove(s.id(), s); // remove only if unchanged (atomic 2-arg remove)
    }

    // 3) Notify after the map is consistent; re-entrant add() is now harmless.
    for (Session s : expired) {
        listener.onEvicted(s);
    }
}

Snippet 11 — Leaked enum default surfaces in a new branch (Python)¶

Difficulty: Hard

class PaymentStatus(Enum):
    PENDING = 0
    AUTHORIZED = 1
    CAPTURED = 2
    REFUNDED = 3
    # FAILED added later

def is_settled(status):
    # Settled means money actually moved and stayed.
    return status.value >= PaymentStatus.CAPTURED.value


# Months later, FAILED is appended:
class PaymentStatus(Enum):
    PENDING = 0
    AUTHORIZED = 1
    CAPTURED = 2
    REFUNDED = 3
    FAILED = 4

# Caller in the reconciliation job:
def owed_to_merchant(payments):
    return sum(p.amount for p in payments if is_settled(p.status))

What's wrong?

class PaymentStatus(Enum):
    PENDING = auto()
    AUTHORIZED = auto()
    CAPTURED = auto()
    REFUNDED = auto()
    FAILED = auto()

    @property
    def is_settled(self):
        # Explicit membership — adding FAILED does not silently include it.
        return self in {PaymentStatus.CAPTURED}

Snippet 12 — Date format decided in two places (Go)¶

Difficulty: Medium

// package exporter — writes a daily report file.
package exporter

func filename(day time.Time) string {
    return "report-" + day.Format("2006-01-02") + ".csv" // ISO date
}

// package cleaner — deletes reports older than 30 days, written by another team.
package cleaner

func isOldReport(name string, now time.Time) bool {
    // Expect "report-01-02-2006.csv" (US format)
    base := strings.TrimSuffix(strings.TrimPrefix(name, "report-"), ".csv")
    day, err := time.Parse("01-02-2006", base)
    if err != nil {
        return false
    }
    return now.Sub(day) > 30*24*time.Hour
}

What's wrong?

package report

const datePrefix = "report-"
const dateLayout = "2006-01-02" // the single source of truth for the filename date

func Filename(day time.Time) string {
    return datePrefix + day.Format(dateLayout) + ".csv"
}

// ParseDay is the inverse of Filename — same layout, by construction.
func ParseDay(name string) (time.Time, error) {
    base := strings.TrimSuffix(strings.TrimPrefix(name, datePrefix), ".csv")
    return time.Parse(dateLayout, base)
}

// cleaner now depends on the owner, not on a re-guessed layout:
func isOldReport(name string, now time.Time) bool {
    day, err := report.ParseDay(name)
    if err != nil {
        return false
    }
    return now.Sub(day) > 30*24*time.Hour
}

Scorecard¶

How did you score?

• 11–12 found: You instinctively ask "who owns this decision?" and spot a fact encoded twice. Senior-level information-hiding judgment.
• 8–10 found: Strong. You catch the duplicated-decision leaks; keep sharpening the eye for shallow abstractions that lose information (Snippets 5, 10).
• 5–7 found: Solid. Re-read the answers and notice the recurring shape: the same fact known in two modules, or a detail the interface failed to hide.
• 0–4 found: Study the chapter README and junior.md, then return. The pattern repeats; once you see it you cannot unsee it.

Related Topics¶

• README.md — the chapter's positive rules: deep modules, information hiding, design it twice
• junior.md — foundations of abstraction and information hiding
• tasks.md — exercises to practice deepening shallow modules
• Anti-Patterns — broader catalog of design smells, including leaky abstractions
• Refactoring — mechanical techniques (Encapsulate Field, Hide Delegate, Move Method) that repair the leaks shown here