The Principle of Least Astonishment can conflict with other goals — performance, security, or introducing a genuinely better abstraction. How do you decide when a deliberate surprise is justified, and how do you manage that across a large system?
answer
- heuristic, not a law — expectations come from history
- audience, exposure, detectability, severity, durability
- a surprise the compiler catches is nearly free
- astonishment budget: consistency is the asset
- recurring explanation = design defect
basics
~20 sAsk whose expectations you are breaking, how often they will hit it, and how bad it is if they guess wrong. Break an expectation only when the gain is large and durable, then make the surprise loud and impossible to miss — in names, types, and tooling.
solid answer
~60 sLeast Astonishment is a heuristic about cognitive load, so it is traded off, not obeyed absolutely. I evaluate a proposed surprise on four axes: **audience** (whose mental model breaks — one team or every consumer?), **exposure** (how many call sites, how often), **detectability** (does the compiler, type system, linter, or a loud name catch a wrong assumption, or does it fail silently in production?), and **severity** (data corruption versus a confusing but harmless result). A surprise with high detectability and low severity is cheap; a silent, high-severity one is almost never worth it. When we accept one, we pay it down: name it explicitly, encode it in types where possible, add a lint or architecture test, and document it in one place people actually read. Across a large system I treat consistency itself as the asset — an *astonishment budget* — and spend it rarely, because every exception charges every future reader. Where a better abstraction genuinely warrants breaking an old convention, we migrate wholesale rather than letting two conventions coexist, since mixed conventions are more astonishing than either alone.
go deeper
Say the principle is a guideline, and that if you must do something unexpected you should make it obvious in the name.
Give a concrete conflict (a cache, or a safe-but-unexpected default) and explain making the surprise explicit and localized.
Provide an evaluation frame — audience, exposure, detectability, severity — plus mechanical enforcement and containing the deviation behind a boundary.
Argue in terms of organization-wide cognitive load and reader-time economics: an astonishment budget, convention governance and decision records, finishing migrations instead of forking conventions, and managing behavior changes as breaking changes across many consumers.
## Why conflicts are real Least Astonishment minimizes the mismatch between expected and actual behavior. But expectations are formed by *history*, and history is sometimes wrong: insecure defaults were once conventional, blocking I/O was once the norm, mutable shared state was once idiomatic. If conventions could never be broken, no design could improve. So the principle must be weighed, not obeyed. Common conflicts: - **Performance.** A cache, a lazy load, or a batched write improves throughput but makes behavior less obvious (stale reads, deferred failures, I/O at surprising moments). - **Security.** The safe default is sometimes the unexpected one — refusing plaintext transport, rejecting unknown fields, expiring sessions aggressively. Here safety should win, with the surprise clearly messaged. - **Better abstraction.** A new model (immutable values, explicit result types, a different concurrency model) initially astonishes everyone precisely because it is unfamiliar, then becomes the new expectation. - **Consistency vs correctness.** Matching a bad existing local convention is less astonishing today and worse forever. Eventually you must break it — and then migrate everything rather than fork the convention. ## A decision frame For any deliberate deviation, ask: 1. **Audience** — whose mental model breaks? A public API breaks strangers you cannot teach; an internal module breaks a team you can. The wider and less reachable the audience, the higher the bar. 2. **Exposure** — how many call sites, how often? A surprise on a hot, frequently-written path costs far more than one in a rarely-touched corner. 3. **Detectability** — will a wrong assumption fail loudly and early (compile error, type mismatch, lint rule, failing test, startup validation) or silently and late (a wrong number in a report six months later)? Detectability is the biggest lever: a surprise the compiler catches is nearly free. 4. **Severity** — worst realistic outcome: mild confusion, an outage, or silent data corruption? 5. **Durability** — will the gain still matter in three years, or is it a temporary optimization that will outlive its justification and become folklore? Accept the surprise when the gain is large and durable *and* detectability is high or severity is low. Reject it when it is silent and severe, however elegant. ## Paying for an accepted surprise - **Move it into the name and the types.** `unsafePerformIO`, `insecureSkipVerify`, `sortInPlace`, `getAndIncrement`, `blockingCall` — the reader is warned at the call site without reading docs. - **Make it mechanically enforced.** A lint rule, an architecture test, a required annotation, or a startup check converts "you had to know" into "the build tells you". - **Localize it.** Confine the unconventional behavior behind one adapter or module so the rest of the codebase keeps the ordinary model. - **Document once, near the code.** Scattered tribal knowledge is not a payment. ## System-scale management Think of an **astonishment budget**: consistency is the asset, each exception is a withdrawal, and readers pay the interest forever. Concretely: - Maintain a small set of explicit conventions (naming, error semantics, effect placement, defaults) instead of relying on individual taste. - Prefer **one convention applied uniformly** over the locally optimal choice in each spot. Two half-adopted conventions are worse than either alone — a migration must finish. - Record deviations with rationale (architecture decision records) so the next team neither re-litigates them nor imitates them by cargo cult. - Watch the **evidence of astonishment**: repeated support questions, misuse patterns in review, the same bug recurring at different call sites, documentation that must explain a behavior over and over. Recurring explanation is a design defect, not a docs defect — if a comment exists to prevent misuse, consider changing the interface instead. - For **evolution**, remember that changing established behavior astonishes existing users even when the new behavior is objectively better. Manage it as a breaking change: deprecation with a working alternative, warnings that name the new behavior, versioned contracts, a finite migration window. ## Failure modes at the extremes Dogmatic application produces stagnation — bad conventions preserved forever and abstractions dumbed down to whatever a newcomer would guess. Ignoring the principle produces a system where every module must be read to be used, which is where onboarding cost and defect rate explode. The senior judgement is recognizing that the principle protects *readers*, and that reader-time is the scarcest resource in a long-lived system.
- Your team wants to introduce explicit result types for errors in a codebase that has used exceptions everywhere. That will astonish every reader. How do you judge it?Weigh durability and detectability against exposure. The gain is durable (failure becomes visible in signatures) and detectability is high (the compiler forces handling), so the surprise is cheap and self-correcting. The real risk is a partial migration leaving two coexisting conventions, which is more astonishing than either. So commit to a bounded scope with a clear boundary rule — result types inside the domain, exceptions translated at the edges — and finish that scope rather than sprinkling both styles.
- How do you detect that a system is accumulating astonishment before it shows up as incidents?Leading indicators: the same question asked repeatedly in review or support, comments that exist only to prevent misuse, wrapper utilities teams write to make an API behave "normally", the same class of bug recurring at different call sites, and onboarding time creeping up. Each says the interface is wrong, not the reader.
Road design: driving on the left astonishes a visitor, but it is consistent, signposted, and everyone survives. A single street that silently reverses direction is a far smaller deviation and far more lethal — the danger is in the unmarked exception, not the convention.
saying these in an interview costs you the question
- Treating the principle as absolute and refusing any unfamiliar abstraction
- Justifying a silent, severe surprise with "it's documented" or "the team knows"
- Leaving two conventions half-migrated and calling it incremental improvement
- Assuming what is unsurprising to the authors is unsurprising to consumers
- Optimizing each module locally for its own readers while ignoring system-wide consistency
- Changing long-established behavior without treating it as breaking because the new behavior is "obviously better"