Skip to main content

Detailed Design

Interfaces, data structures, and boundary conditions, down on paper. This part covers how, in detailed design, to turn my plausible-looking plans into ones that hold up under edge-case scrutiny.

Missing edge cases

The code I hand you almost always runs on the main path. But null, empty collections, out-of-range indices, oversized strings, concurrency, time zones, encoding — if you don't say them out loud, I routinely skip them. The code looks complete; feed it one edge input and it breaks. This entry is about omissions at the implementation-detail level; if the whole design's robustness assumptions don't hold, see The design looks right but doesn't survive edge cases.

HighEngineer

Plausible but brittle design

I give you a design that's self-consistent under normal inputs and reads as reasonable, so you adopt it. But it falls apart the moment it scales up, hits an exceptional path, or meets concurrency or retries on failure — the problem isn't one line of code, it's the robustness assumptions the design quietly leans on. This entry is about fragility at the design level; if you missed a specific edge branch while writing the implementation, see When I write the implementation, I miss the edge branches you didn't spell out.

HighEngineer

Concurrency races

I default to writing code as if it's "single-threaded, sequential, with no one touching it at the same time," so I miss race conditions, don't lock shared state, leave check-then-act non-atomic, and skip transactions or optimistic locking on the database. Functional tests (single-threaded) all go green, then under concurrency it intermittently loses updates, corrupts data, or deadlocks. This is about concurrency correctness — a specific, hidden class of defect — not the same as missing branches at the implementation level or the overall robustness of a design.

HighEngineer · Architect

Filesystem order assumptions

I default to treating file-system operations and events as if they happen in a deterministic, serialized, predictable order — write a file and you can immediately read back its complete contents, watcher events arrive one at a time in modification order, readdir returns entries in creation or alphabetical order, a file appearing means it's done being written. So I treat "file appeared" as a synchronization signal and a watcher as an ordered log, and the code runs fine on my fast local disk, then intermittently breaks on another machine, another OS, or under a little load. This is about false determinism at the OS / file-system layer — not the same as concurrency races (races on shared in-memory / database state) or missing edge cases (you forgot an input).

MediumEngineer · Architect