Hyrum's Law
Hyrum's Law is a principle in software engineering that states: "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." Named after Google engineer Hyrum Wright, this law captures a fundamental challenge in software development and system design. It observes that regardless of what documentation specifies or what developers intend, users will inevitably rely on every detectable aspect of a system's behavior—including bugs, performance characteristics, timing, error messages, and implementation details that were never meant to be part of the official interface.
The significance of Hyrum's Law lies in its implications for maintaining and evolving software systems. It explains why seemingly innocuous changes can break existing implementations, even when those changes don't violate any documented contracts. For instance, if a function happens to return results in alphabetical order as a side effect of its implementation, users will eventually write code that depends on that ordering, even if it was never guaranteed. This creates implicit contracts that constrain future changes and make refactoring difficult.The law highlights the tension between implementation flexibility and backward compatibility. It suggests that the larger the user base, the more constrained developers become in their ability to modify systems without causing breakage. This has profound implications for API design, versioning strategies, deprecation policies, and technical debt management. Understanding Hyrum's Law encourages developers to be more deliberate about what behaviors they expose, to use encapsulation and abstraction more carefully, and to plan for the reality that users will depend on virtually everything they can observe.
The significance of Hyrum's Law lies in its implications for maintaining and evolving software systems. It explains why seemingly innocuous changes can break existing implementations, even when those changes don't violate any documented contracts. For instance, if a function happens to return results in alphabetical order as a side effect of its implementation, users will eventually write code that depends on that ordering, even if it was never guaranteed. This creates implicit contracts that constrain future changes and make refactoring difficult.The law highlights the tension between implementation flexibility and backward compatibility. It suggests that the larger the user base, the more constrained developers become in their ability to modify systems without causing breakage. This has profound implications for API design, versioning strategies, deprecation policies, and technical debt management. Understanding Hyrum's Law encourages developers to be more deliberate about what behaviors they expose, to use encapsulation and abstraction more carefully, and to plan for the reality that users will depend on virtually everything they can observe.
Applications
- Software engineering and API design
- System architecture and microservices
- Library and framework development
- Platform engineering and infrastructure
- Open source software maintenance
- Database schema evolution
- Web browser development and web standards
- Operating system development
- Backward compatibility planning
- Technical debt assessment
Speculations
- Social norms and etiquette: Just as users depend on unintended system behaviors, people may come to rely on incidental social patterns that were never formally established, making cultural evolution difficult
- Language evolution: Speakers might depend on quirks, grammatical irregularities, or pronunciation variations that become locked into usage despite not being part of formal rules
- Organizational behavior: Employees may build workflows around unintended side effects of policies, making policy reform harder than anticipated
- Ecological systems: Species might evolve dependencies on incidental environmental features, creating fragility when those features change
- Legal interpretation: People may structure their behavior around unintended implications of laws, creating dependencies that constrain future legislation
- Economic markets: Traders might depend on peculiar market microstructure details that become implicit contracts
- Educational pedagogy: Students may develop learning strategies based on unintended test-taking patterns rather than actual knowledge assessment
References