Hyrum's law

expression

programming

With enough users, every observable behavior of your system will be depended on by somebody, contract or not.

Coined by Google engineer Hyrum Wright, the law explains why 'we never promised that' does not prevent breakage: users bind to timing, error strings, ordering, and undocumented quirks, so the de facto interface is everything observable. xkcd 1172 ('every change breaks someone's workflow') is its comic form. It is the deep reason behavior-preserving refactors still page someone at 3 a.m.

With a sufficient number of users, every observable behaviour of your system will be depended on by somebody, regardless of what you promised in the contract. Hyrum Wright's observation is that the interface you documented and the interface you actually have are different things, and the second one is larger.

The consequences are counterintuitive. Fixing a bug can break users who worked around it. Making something faster can break users who relied on the previous timing. Changing the order of results from an unordered collection breaks whoever assumed the order was stable, and they were wrong to assume it, and their code still worked until you changed it. Error message text becomes an API the moment somebody parses it.

The practical responses are all about reducing observability rather than strengthening documentation, because documentation does not constrain what people do. Deliberately randomizing what is genuinely unordered stops the dependency forming. Versioning lets old behaviour persist for those who need it. And at sufficient scale, the honest position is that you cannot fix everything, so you choose which breakages to accept and communicate them, which is a very different activity from believing your contract protects you.

All glossary entries