Least astonishment

Why is a correct interface that surprises the person using it a defect?

Suppose a function does exactly what its documentation says, has no bugs, and passes every test. But everyone who uses it for the first time gets it wrong, because it does something they did not expect — a getter that also writes to disk, a delete that returns before anything is deleted, a sort that quietly reorders equal items.

The principle of least astonishment says this is a defect. That is a strong claim: the code is correct, and the mistake is being made by the reader. On what grounds do we charge the interface for someone else's wrong guess?

Start by asking how anyone uses an interface at all. Nobody reads the whole specification of every function they call; there is not time, and much of it is not written. What they do instead is predict. They look at a name, a signature, the surrounding library, and their experience of a hundred similar things, and form an expectation of what the call will do. Then they call it and move on.

So the prediction is not laziness — it is the only mechanism by which large systems get used. That expectation is a mental model: an internal account of how the thing behaves, assembled mostly from evidence the designer supplied.

Now ask where that evidence came from. Almost all of it is under the designer's control. The name is a signal. The type is a signal. Being one function among nine consistent siblings is a signal. Matching the convention of the language, or of the popular library everyone arrives from, is a signal. The interface is broadcasting a claim about its behaviour whether or not anyone intended it to.

That is the move that settles the question. If the interface emits signals and the signals are misleading, the wrong prediction is not a private error by the reader — it is a response to what was published. The documentation may say otherwise, but documentation is the channel used least and consulted last, usually only after something has already gone wrong. Charging the defect to the interface follows from noticing who controls the evidence.

Push on the cost, because "surprising" sounds merely inelegant. What does a surprise actually cost? First, misuse that runs: the call did something the caller did not intend, and nothing failed, so the bug ships. Second, a permanent tax on reading — once one function in a library has betrayed its name, every other name in it becomes untrustworthy, so readers must verify things they could previously assume. That second cost is the larger one, and it is superlinear: a single inconsistency degrades confidence across the whole surface, because consistency is exactly what made prediction possible.

And notice what consistency is doing, information-theoretically. A convention lets one learned fact cover a hundred cases. Every exception cancels that compression for the whole set, since a reader can no longer tell which member is the exception without checking each one. This is why "it is documented" is a weak defence — documentation restores the fact, but not the ability to generalise from it.

There is a genuine tension to be honest about. Least astonishment is measured against the expectations of a particular audience, and audiences disagree. Zero-based indexing astonishes a spreadsheet user and would astonish a C programmer if it were otherwise. The principle is therefore not "be intuitive in the abstract" — there is no such thing — but "be predictable from the conventions your intended users already hold". That makes it a design question about who the users are, not a universal ranking of behaviours.

And sometimes the surprising behaviour is genuinely required: the operation really must be asynchronous, or lossy, or destructive. The principle does not forbid that. It says the surprise must be moved into the loudest channel available rather than left in the documentation — rename the function so the surprise is in the name, change the return type so the caller cannot ignore it, require an explicit flag. The astonishment is not removed; it is relocated to where prediction happens.

Three refinements.

First, "surprising" is not the same as "unfamiliar". Learning a genuinely new concept is effortful and that is fine; the principle concerns cases where the interface invited a specific wrong prediction. A novel abstraction with a novel name astonishes nobody. A familiar name with a novel meaning astonishes everybody.

Second, the strongest fixes are structural rather than nominal. Renaming helps; making the mistake impossible helps more. If a call must not be made twice, the type that permits it can be consumed by the first call. If a result must not be ignored, mark it so the compiler complains. These convert a prediction into a checked fact, which is the only fix that does not rely on anyone reading anything.

Third, the principle applies most sharply to defaults. A default is what happens when the user has expressed no opinion at all, which means it is pure prediction with no signal to correct it. A surprising default is therefore the most expensive kind of surprise — and defaults that are safe when wrong are worth a good deal of performance.

• How making illegal states unrepresentable turns a convention into something the compiler enforces.
• Whether the same reasoning explains why inconsistent error handling within one library is more damaging than a uniformly awkward scheme.

Every term the collection defines is gathered in the glossary.