Hyrum’s Law is a fairly new coinage. During an entertaining, Goofus & Gallant-themed 2015 talk at CppCon about writing good tests, Google engineers Titus Winters and Hyrum Wright spent some time talking about writing tests that are resilient against changing the implementation, which is complicated because of a tendency of engineers everywhere (even at Google) to write code and make tests that have “deep dependence” beyond what the interface specifies. Winters and Wright cited a sort of natural law about how eventually the official published interface and the interface specified by its current implementation become blurred in users’ minds and their code, and attributed it as “Hyrum’s Law.” Later, Winters cited this law in a more concise form:
“With a sufficient number of users of an interface, it doesn’t matter what you promised in the interface contracts, all observable behaviors of your class or function or whatnot will be depended upon by somebody.”
I can think of several reasons why this is true and resonant. Foremost among them is that documentation is important for an API, but it’s also often a lousy resource for trying to glue together what a library provides and what your system needs. The needs of a system are often deep (requiring much of specific API features) but not broad (not requiring many features relative to what all the API provides). Documentation that’s complete is often the opposite: broad but not deep.
Despite the fact that documentation exists, oftentimes programmers still need to “poke & prod” at a library to fully understand how it works. This can address topics such as timing, synchronicity, return value properties, accepted inputs, and lifecyles, which aren’t always covered in published APIs. Complicating this is that a published API may not even cover all the features available in the underlying implementation; perhaps they will be in the future, but you as the system developer need that feature now. Ask me some time about Bing Maps if you ever want a real world example.
The end result of this is that a library with a published API seeing any non-trivial amount of use will break things for users when doing any upgrade, fix, or refactor, even when the published API has not changed. This is software; everything is broken from the time it is written.
I’ve already given away half of the biographical section, but to reiterate, Hyrum Wright is a core software engineer at Google. He’s also a member of the Apache Software Foundation and spent four years as the release manager for Subversion. Wright received his Ph.D. from UT Austin and has been working at Google since 2012, coincidentally the same year I got my red badge there.
Extra Notes:
- The original version of this post cited a 2016 CppCast appearance by Winters as the first public coining of Hyrum’s Law — the quoted text of the law comes from a recap of that podcast. Thanks to Chuck Wilcox for finding the earlier 2015 reference.
- Google’s core software is kept in a single repository of 2 billion lines of code in 9 million files, including over 100,000 test runners. So if you’re doing development on libraries in this environment, you can get fast feedback on how it will affect everything just by running builds and test suites already in your source tree.