Hyrum's Law of Implicit Dependencies

Hyrum Wright is a Staff Software Engineer at Google, according to his LinkedIn profile. He made an observation nowadays called "Hyrum's Law". It regards interfaces and API design and should be considered and memorized by anyone employed in the software engineering sector.

Hyrum's Law#

Definitions#

To fully understand the impact of this sentence, we have to define a few things:

• API - Any occurrence of an interface
• Interface - Not the concrete code pattern such as in Java, for example, but the abstract concept that defines the exposure of any consumable functions

Significance and Meaning#

Hyrum himself called this observation "The Law of Implicit Dependencies". But people at Google spread the name "Hyrum's Law" for the apparent reason of briefness. However, that's also why nobody not knowing about it will understand what's meant.

A colloquial interpretation of this law could be: "Every change breaks someone's workflow", as ridiculously shown in a comic on https://xkcd.com/1172/. But to understand that, we have to take a step back and look at the big picture: Anyone exposing his code as (re)usable functions inside a project, or for example, as a RESTful APIs outside the project, usually does that for the sake of people to explicitly use the code. However, by the laws of statistics, all the observable behaviors your code supplies will eventually be used by someone, thereby implicitly assuming things.

Example#

To grasp what these abstract sentences actually mean, take this example: You build an API that publicly delivers cat facts:

{
  "catfacts": [
    "fact"
    :
    {
      "number": 1,
      "text": "Cats have 230 bones while humans only have 206."
    },
    "fact"
    :
    {
      "number": 2,
      "text": "Cats live longer if they live indoor."
    }
  ]
}

Given this information, people will implicitly assume that this interface serves cat facts in ascending order regarding their number. Meaning if the API delivers these facts in a random order, it will break someone's system at some point if they, for example, always ship the first fact as the latest one. Or even less obvious: the API orders the items concerning their first digit of the number.

{
  "catfacts": [
    "fact"
    :
    {
      "number": 1,
      "text": "Cats have 230 bones while humans only have 206."
    },
    "fact"
    :
    {
      "number": 10,
      "text": "Abraham Lincoln had 4 cats that lived in the white house with him"
    },
    "fact"
    :
    {
      "number": 2,
      "text": "Cats live longer if they live indoor."
    },
    ...
  ]
}

This will also lead to a system or workflow breaking at some point. And it may be unfathomable to its maintainers why that is. The same applies to explicit changes, such as introducing a new ORM on the backend side that leads to the items being delivered in the inverted order. Funny things can happen now if people try to fix this naively.

Consequences of Hyrum's Law#

The problem should be apparent by now. But what are the implications for software engineers, teams, and consumers?

The most straightforward answer could be: "Don't change anything". But that's ridiculous again. Anyone working in the computer science industry will confirm that "nothing is as constant as change", and change is, in fact, a good thing, as it's the foundation of any improvement and innovation.

The uncomfortable answer is: we have to take this into account and mind as a software engineer and a consumer of these APIs.

• As the developer, we should provide as much information explicitly as possible, most likely in the documentation. This will reduce the number of people that make implicit assumptions about the API
• As the consumer, we should assume as little as possible about APIs we consume. Of course, there will still be assumptions made, but if you keep in mind that they are assumptions, you may save hours debugging your code.
• As a software architect, we should plan APIs thoroughly to minimize behavioural changes. New behaviour should belong to new endpoints.

TLDR;#

• Hyrum's law basically means: Whatever you deliver, someone is going to use it in a way you never imagined
• Change is necessary and will eventually break someone's system
• Give more explicit information on your interface to reduce the number of implicit assumptions
• Make fewer assumptions about code and, if applicable, test its behavior