Hash ordering and Hyrum's Law – Eddie Aftandilian – Developer tools at GitHub. Previously Java at Google. Views are my own.
With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.
What are the consequences of Hyrum’s Law? Well, it means that anyone trying to do a large-scale migration is going to tear their hair out discovering that their seemingly simple migration is way harder than expected, and that despite putting that giant warning in your docs not to depend on some implementation-specifc behavior, your clients are going to depend on it anyway.
Generally, when you iterate over the keys and values in a hash table, the iteration order is unspecified and implementation dependent. For example, the Javadoc for java.util.HashMap states, “This class makes no guarantees as to the order of the map; in particular, it does not guarantee that the order will remain constant over time.” In practice, HashMap iteration order is stable for several years but is sometimes perturbed by major Java version updates.
Because the iteration order remains stable for years at a time, users end up depending on it, despite the warning in the Javadoc. Now let’s say you’re on the Java team at a large company with a monorepo, and you’re responsible for updating the monorepo from version N of Java to version N + 1. There may be thousands of places where users depend on the hash iteration order.
