Comparison
EncapsulationvsHyrum's law
Encapsulation
another team reached into the field directly, and now you cannot rename it without breaking them.
Keeping a module's internals private so they stay changeable. The value is not secrecy — it is that whatever you expose becomes a contract you have to honour, and whatever you hide stays yours. Every leaked internal converts a future refactor from a local decision into a negotiation with everyone who reached in, which is the mechanism behind Hyrum's law.
Full entry →Hyrum's law
you changed the order of a JSON response and a customer's integration broke, and nowhere did you promise an order.
With enough users, every observable behaviour of your system will be depended on by somebody, regardless of what you documented. Response ordering, timing, error message wording, the number of decimal places — all of it becomes contract by use. It is the reason internal-only rarely stays internal-only and the reason a deprecation plan is a negotiation about actual usage rather than about what the specification said.
Full entry →