Coupling & State Anti-Patterns — Find the Bug¶

Category: Design Anti-Patterns → Coupling & State — modules that know or share too much, so behavior leaks across boundaries no signature admits to. Covers (collectively): Singletonitis · Circular Dependency · Action at a Distance · Hidden Dependencies · Sequential Coupling

This file is critical-reading practice. Each snippet below is a plausible chunk of real-world code in Go, Java, or Python. Read it the way a good reviewer does — slowly, suspicious of what isn't on the screen — and answer three questions:

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

Coupling-and-state anti-patterns are uniquely nasty because the damage is non-local. A function's signature says it needs two arguments; in truth it reads a clock, an env var, and a package-global someone mutated three files away. The compiler is happy. The test passes on your laptop and fails in CI. A method works on Tuesday and crashes on Wednesday because something else ran first. These are the bugs labeled "flaky," "spooky," or "works on my machine" — and they are almost always coupling and hidden state in disguise.

So the "bug" here is often a latent functional or concurrency defect that only fires under a second thread, a different environment, a particular call order, or a particular import graph. Several snippets contain a real, reproducible bug; at least one looks suspicious but is actually justified (a true process-wide singleton, or a sequence safely enforced by with/defer). Don't pattern-match on shape — trace the state and the dependencies.

How to use this file: read each snippet and write your own answer before expanding the collapsible. The skill you're training is noticing the coupling, not recalling the name.

Table of Contents¶

1. The counter everyone shares
2. Two packages that need each other
3. The parser that opens, reads, closes
4. A discount that knows what day it is
5. The sort that reaches across the room
6. The connection pool, globally
7. The two modules and their init order
8. The uploader with three steps
9. The price formatter that reads the locale
10. The registry that imports its plugins
11. The metrics object everybody pokes
12. The HTTP client builder
13. The logger, the config, and the clock
14. The cache singleton with a setter

Snippet 1 — The counter everyone shares¶

// Go — a request-ID generator used by every handler in the service
package idgen

var counter int64

func Next() int64 {
    counter++          // "it's just an increment"
    return counter
}

// used from many concurrent HTTP handlers:
func handler(w http.ResponseWriter, r *http.Request) {
    id := idgen.Next()
    // ... attach id to logs, response, trace ...
}

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

type IDGen struct{ counter int64 }

func (g *IDGen) Next() int64 {
    return atomic.AddInt64(&g.counter, 1)   // atomic; no torn reads, no lost updates
}
// Construct one and inject it; tests get their own, no shared global to race.

Snippet 2 — Two packages that need each other¶

// Go — package user
package user

import "myapp/order"

type User struct {
    ID     int64
    Orders []*order.Order
}

func (u *User) LatestOrder() *order.Order { return order.Latest(u.ID) }

// Go — package order
package order

import "myapp/user"

type Order struct {
    ID    int64
    Buyer *user.User    // back-reference to the owner
}

func Latest(userID int64) *Order { /* ... */ }
func OwnerOf(o *Order) *user.User { return user.Load(o.Buyer.ID) }

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

// package domain — no imports of user/order
type UserID int64
type Order struct { ID int64; BuyerID UserID }
type User  struct { ID UserID }

Snippet 3 — The parser that opens, reads, closes¶

# Python — reads and parses a config file
class ConfigFile:
    def __init__(self, path):
        self._path = path
        self._fh = None

    def __enter__(self):
        self._fh = open(self._path, "r")
        return self

    def __exit__(self, *exc):
        if self._fh:
            self._fh.close()
            self._fh = None

    def read_all(self):
        return self._fh.read()    # only valid between __enter__ and __exit__


# usage
with ConfigFile("app.toml") as cfg:
    text = cfg.read_all()
    settings = parse(text)

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

Snippet 4 — A discount that knows what day it is¶

# Python — computes a "happy hour" discount
from datetime import datetime

def happy_hour_price(base_price):
    now = datetime.now()                  # reaches out to the wall clock
    if 16 <= now.hour < 18:               # 4pm–6pm local time
        return round(base_price * 0.8, 2)
    return base_price


# the test that "passes":
def test_happy_hour():
    assert happy_hour_price(100) == 80     # green at 5pm, red at 9am

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

def happy_hour_price(base_price, now):           # time is now an argument
    if 16 <= now.hour < 18:
        return round(base_price * 0.8, 2)
    return base_price

# production passes a real clock; tests pass a fixed instant — deterministic:
def test_happy_hour():
    five_pm = datetime(2026, 6, 9, 17, 0)
    assert happy_hour_price(100, five_pm) == 80

Snippet 5 — The sort that reaches across the room¶

# Python — a reporting module
rows = []                       # module-level "current working set"

def load(report_rows):
    global rows
    rows = report_rows

def sort_by_date():
    rows.sort(key=lambda r: r["date"])      # in place, mutates the shared list

def top_n(n):
    return rows[:n]


# elsewhere, in an unrelated feature:
def export_csv(data):
    rows_local = data
    rows_local.sort(key=lambda r: r["name"])   # same list object if caller passed `rows`
    write_csv(rows_local)

# the call site that breaks:
load(fetch_rows())
sort_by_date()
export_csv(rows)          # someone passes the module global to the exporter
print(top_n(3))           # expected: 3 earliest by date — but they're now by name

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

def sorted_by_date(report_rows):
    return sorted(report_rows, key=lambda r: r["date"])   # returns a new list

def export_csv(data):
    write_csv(sorted(data, key=lambda r: r["name"]))      # sorted(), not .sort()

# call site — explicit flow, no aliasing surprises:
data = fetch_rows()
print(sorted_by_date(data)[:3])
export_csv(data)        # cannot disturb anyone else's view of the data

Snippet 6 — The connection pool, globally¶

// Go — the database access layer
package db

import "database/sql"

var pool *sql.DB     // one pool for the whole process

func Init(dsn string) error {
    p, err := sql.Open("postgres", dsn)
    if err != nil {
        return err
    }
    p.SetMaxOpenConns(20)
    pool = p
    return nil
}

func Pool() *sql.DB { return pool }

// main.go
func main() {
    if err := db.Init(os.Getenv("DATABASE_URL")); err != nil {
        log.Fatal(err)
    }
    // ... start server; handlers call db.Pool().QueryContext(...) ...
}

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

type Store struct{ pool *sql.DB }

func New(dsn string) (*Store, error) {
    p, err := sql.Open("postgres", dsn)
    if err != nil {
        return nil, err
    }
    p.SetMaxOpenConns(20)
    return &Store{pool: p}, nil     // a Store is never half-built; no nil-pool window
}

func (s *Store) Users() *sql.DB { return s.pool }
// main constructs one *Store and passes it down; tests construct their own.

Snippet 7 — The two modules and their init order¶

# Python — module config.py
import registry

DEFAULTS = registry.build_defaults()   # runs at import time

TIMEOUT = DEFAULTS["timeout"]

# Python — module registry.py
import config

_REGISTRY = {}

def build_defaults():
    return {"timeout": config.TIMEOUT, "retries": 3}    # reads config.TIMEOUT

def register(name, obj):
    _REGISTRY[name] = obj

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

# registry.py — no import of config; takes what it needs as an argument
_REGISTRY = {}

def build_defaults(timeout):
    return {"timeout": timeout, "retries": 3}

# config.py — define plain values first; compose lazily, not at import time
import registry

TIMEOUT = 30

def defaults():                       # function, evaluated on demand
    return registry.build_defaults(TIMEOUT)

Snippet 8 — The uploader with three steps¶

// Java — multipart upload to object storage
public class Uploader {
    private String uploadId;
    private List<String> parts = new ArrayList<>();
    private boolean finished;

    public void begin(String key) {
        this.uploadId = storage.initiate(key);   // must be first
    }

    public void addPart(byte[] chunk) {
        String etag = storage.upload(uploadId, chunk);   // NPE if begin() not called
        parts.add(etag);
    }

    public String complete() {
        finished = true;
        return storage.complete(uploadId, parts);   // garbage if addPart never ran
    }
}

// a caller, refactored under time pressure:
Uploader u = new Uploader();
u.addPart(firstChunk);     // forgot begin()
u.begin("report.csv");
u.complete();              // "completes" an upload with zero parts

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

public final class Uploader {
    public static Session begin(String key) {       // entry point returns the next state
        return new Session(storage.initiate(key));
    }
    public static final class Session {
        private final String uploadId;
        private final List<String> parts = new ArrayList<>();
        private Session(String id) { this.uploadId = id; }

        public Session addPart(byte[] chunk) {        // only callable on a live Session
            parts.add(storage.upload(uploadId, chunk));
            return this;
        }
        public String complete() {
            if (parts.isEmpty()) throw new IllegalStateException("no parts uploaded");
            return storage.complete(uploadId, parts);
        }
    }
}

// caller cannot call addPart/complete without begin — the type system enforces order:
String etag = Uploader.begin("report.csv").addPart(firstChunk).complete();

Snippet 9 — The price formatter that reads the locale¶

# Python — formats money for display
import locale

def format_price(amount):
    locale.setlocale(locale.LC_ALL, "")     # use the process's current locale
    return locale.currency(amount)


# called from two places in the same process:
def invoice_line(amount):
    return format_price(amount)

def admin_report(amount):
    # a different feature set the locale earlier for German number formatting:
    # locale.setlocale(locale.LC_ALL, "de_DE.UTF-8")
    return format_price(amount)

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

from babel.numbers import format_currency   # locale-aware without global mutation

def format_price(amount, *, currency: str, locale: str) -> str:
    return format_currency(amount, currency, locale=locale)

def invoice_line(amount):
    return format_price(amount, currency="USD", locale="en_US")

def admin_report(amount):
    return format_price(amount, currency="EUR", locale="de_DE")

Snippet 10 — The registry that imports its plugins¶

# Python — handlers/__init__.py, a plugin registry
HANDLERS = {}

def register(event_type):
    def deco(fn):
        HANDLERS[event_type] = fn
        return fn
    return deco

def dispatch(event):
    return HANDLERS[event["type"]](event)    # KeyError if plugin not imported


# handlers/email.py
from handlers import register

@register("email.send")
def send_email(event): ...

# main.py
from handlers import dispatch

dispatch({"type": "email.send", "to": "a@b.com"})   # at startup

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

# explicit assembly — the dependency is visible and ordered on purpose
from handlers.email import send_email
from handlers.sms import send_sms

def build_dispatcher():
    handlers = {
        "email.send": send_email,
        "sms.send": send_sms,
    }
    def dispatch(event):
        handler = handlers.get(event["type"])
        if handler is None:
            raise ValueError(f"no handler for {event['type']!r}")
        return handler(event)
    return dispatch

dispatch = build_dispatcher()    # all handlers present before first dispatch

Snippet 11 — The metrics object everybody pokes¶

// Java — application-wide metrics
public final class Metrics {
    public static int requestsInFlight = 0;     // public, static, mutable
    public static long totalErrors = 0;
}

// in the request filter:
Metrics.requestsInFlight++;
try {
    chain.doFilter(req, resp);
} catch (Exception e) {
    Metrics.totalErrors++;
    throw e;
} finally {
    Metrics.requestsInFlight--;
}

// in a background reporter thread, every 10s:
log.info("in flight: " + Metrics.requestsInFlight + ", errors: " + Metrics.totalErrors);

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

public final class Metrics {
    private final AtomicInteger requestsInFlight = new AtomicInteger();
    private final LongAdder      totalErrors      = new LongAdder();  // high-contention counter

    public void enter()  { requestsInFlight.incrementAndGet(); }
    public void exit()   { requestsInFlight.decrementAndGet(); }
    public void error()  { totalErrors.increment(); }

    public int  inFlight() { return requestsInFlight.get(); }
    public long errors()   { return totalErrors.sum(); }
}
// Construct one Metrics, inject it into the filter and the reporter — no public static state.

Snippet 12 — The HTTP client builder¶

// Java — a configurable HTTP client; fields set fluently, then used
public class ApiClient {
    private String baseUrl;
    private Duration timeout;
    private String authToken;

    public ApiClient baseUrl(String u)   { this.baseUrl = u; return this; }
    public ApiClient timeout(Duration t) { this.timeout = t; return this; }
    public ApiClient token(String t)     { this.authToken = t; return this; }

    public Response get(String path) {
        // builds the request from the fields set so far
        return transport.send(baseUrl + path, timeout, authToken);
    }
}

// two call sites in the codebase:
ApiClient client = new ApiClient().baseUrl("https://api.example.com").token(tok);
Response a = client.get("/users");      // timeout is null

// elsewhere, the SAME shared client instance (it's a @Singleton bean):
client.timeout(Duration.ofSeconds(2));  // someone "configures" it at runtime
Response b = client.get("/orders");     // now everyone's timeout changed

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

public final class ApiClient {                 // immutable once built
    private final String baseUrl;
    private final Duration timeout;
    private final String authToken;

    private ApiClient(Builder b) {
        this.baseUrl = Objects.requireNonNull(b.baseUrl);
        this.timeout = Objects.requireNonNull(b.timeout);   // missing config fails at build, not at get()
        this.authToken = b.authToken;
    }
    public Response get(String path) { return transport.send(baseUrl + path, timeout, authToken); }

    public static final class Builder {
        private String baseUrl, authToken; private Duration timeout;
        public Builder baseUrl(String u)   { this.baseUrl = u; return this; }
        public Builder timeout(Duration t) { this.timeout = t; return this; }
        public Builder token(String t)     { this.authToken = t; return this; }
        public ApiClient build()           { return new ApiClient(this); }
    }
}

// build once, fully validated; share the immutable instance freely — no one can re-mutate it:
ApiClient client = new ApiClient.Builder()
    .baseUrl("https://api.example.com").timeout(Duration.ofSeconds(2)).token(tok).build();

Snippet 13 — The logger, the config, and the clock¶

// Go — writes an audit entry
package audit

import (
    "fmt"
    "os"
    "time"
)

func Record(action string) error {
    env := os.Getenv("APP_ENV")               // hidden dep #1: environment
    if env == "" {
        env = "dev"
    }
    line := fmt.Sprintf("[%s] %s %s\n",
        time.Now().UTC().Format(time.RFC3339), // hidden dep #2: wall clock
        env, action)
    f, err := os.OpenFile(auditPath(), os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
    if err != nil {
        return err
    }
    defer f.Close()
    _, err = f.WriteString(line)               // hidden dep #3: filesystem path
    return err
}

func auditPath() string { return "/var/log/app/audit.log" }   // hard-coded

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

type Auditor struct {
    Env   string
    Now   func() time.Time   // inject the clock; tests pass a fixed one
    Out   io.Writer          // inject the sink; tests pass a bytes.Buffer
}

func (a *Auditor) Record(action string) error {
    line := fmt.Sprintf("[%s] %s %s\n",
        a.Now().UTC().Format(time.RFC3339), a.Env, action)
    _, err := io.WriteString(a.Out, line)
    return err
}

// production wires real values; a test wires a fake clock + buffer and asserts the exact line:
a := &Auditor{Env: "test", Now: func() time.Time { return fixed }, Out: &buf}

Snippet 14 — The cache singleton with a setter¶

# Python — a global cache used across the app
class Cache:
    _instance = None

    @classmethod
    def instance(cls):
        if cls._instance is None:
            cls._instance = cls()
        return cls._instance

    def __init__(self):
        self._store = {}

    def get(self, key):
        return self._store.get(key)

    def set(self, key, value):
        self._store[key] = value


# feature A — caches the *current tenant's* permission set under a fixed key:
def load_permissions(tenant_id):
    perms = Cache.instance().get("permissions")
    if perms is None:
        perms = db.fetch_permissions(tenant_id)
        Cache.instance().set("permissions", perms)    # one global key for all tenants
    return perms

What anti-pattern(s) are present? What concrete problem(s) does it cause? How would you fix it?

class Cache:                                  # a plain object, not a hidden global
    def __init__(self):
        self._store = {}
    def get(self, key):       return self._store.get(key)
    def set(self, key, value): self._store[key] = value

def load_permissions(tenant_id, cache):       # cache injected, not Cache.instance()
    key = ("permissions", tenant_id)          # scoped per tenant — no cross-leak
    perms = cache.get(key)
    if perms is None:
        perms = db.fetch_permissions(tenant_id)
        cache.set(key, perms)
    return perms

Summary — patterns of spotting¶

You don't spot coupling-and-state anti-patterns by reading a single line — you spot them by asking "what does this depend on that the signature doesn't admit, and who else can change what it touches?" The repeatable moves from these fourteen snippets:

• Read the signature, then hunt for inputs it doesn't declare. A clock (now()), an env var (getenv), a locale, a filesystem path, a global registry, random — every ambient read is a Hidden Dependency that makes the function behave differently in tests and in another environment (Snippets 4, 9, 13). The cure is always the same: pass it in.
• Find the shared mutable state and trace who writes it. A package-global counter (Snippet 1), a global list aliased into another feature (Snippet 5), a process-wide locale (Snippet 9), a mutable singleton config/cache (Snippets 12, 14) — when two unrelated places write the same state, editing one mysteriously changes the other. That's Action at a Distance; the bug is non-local and "each function looks fine alone."
• Under concurrency, every unsynchronized shared write is a bug. counter++, requestsInFlight++, a plain HashMap/int/long touched by many threads → lost updates and torn reads (Snippets 1, 11). go test -race and the Java Memory Model are not optional. Make it atomic and prefer injecting the state over globalizing it.
• Map the import graph; it must be a DAG. A→B→A is a Circular Dependency — a compile error in Go (Snippet 2), and a far nastier init-order crash in Python/Java where the cycle is tolerated until module-level code reads a half-initialized neighbor (Snippet 7). Break it with a third leaf package or an inverted interface, and keep real work out of import-time code.
• For every "you must call these in order" object, ask: is the order enforced? Unenforced sequences crash or silently succeed wrong (Snippets 8, 12) — Sequential Coupling. The cure is to make illegal orders unrepresentable: a phased/Builder API, a state machine, or a scope construct. A sequence already wrapped in with/defer/RAII (Snippet 3) is the fix, not the disease — don't flag it.
• Resist false positives. Not every global is Singletonitis: a single *sql.DB pool per process is correct (Snippet 6), and a true process-wide resource is the legitimate exception. The danger is global reach + mutable shared state, not the count of instances. Inject even your singletons so tests stay isolated.

The meta-lesson: coupling bugs are bugs of omission and reach. The defect isn't a line you can point at — it's an input nobody declared, a global someone else mutated, an order nobody enforced, or an import cycle that decided initialization order for you. A hidden clock made a test flaky; a shared list reordered another feature's data; an unsynchronized counter handed out duplicate IDs; a global cache leaked one tenant's permissions to all of them. When behavior depends on where, when, in what order, or who ran first — look for the coupling, because the bug is hiding in the state nobody passed explicitly.

Related Topics¶

• junior.md — what each of the five coupling shapes looks like and why it's bad.
• middle.md — when these creep in and the small countermove that reverses them.
• senior.md — detecting and migrating these at scale in review.
• tasks.md — exercises that build the same muscles from the writing side.
• optimize.md — flawed designs to redesign end-to-end.
• interview.md — Q&A across all levels.
• Clean Code → Classes — SRP and the dependency-injection cure for hidden globals.
• Clean Code → Immutability — immutable config that's safe to share kills Action at a Distance.
• Clean Code → Concurrency — the memory-model rules behind the data races above.
• Clean Code → Modules and Packages — keeping the dependency graph a DAG.
• Design Patterns → Creational — Builder and the state machine that encode required call order.
• OO Misuse — Find the Bug and Abstraction Failures — Find the Bug — the sibling find-bug files in this chapter.