Hyrum's law

Giovanni Gorgone — Thu, 02 Feb 2023 02:15:14 +0000

You are making a small, harmless change to the code. You stop, you know that you'll upset someone. Have you ever felt this way? This is exactly what Hyrum's law 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.”

To understand it better, let's analyze the elements involved.

What is an API? An API is the boundary between the user and the product/service.

The API of a TV remote control is composed of its buttons. They are used by users who don't need to know what's happening inside the remote control. What happens inside the remote control is called "implementation". What's the advantage of this distinction? The advantage is that the implementation can change without the user having to worry about it.

The contract of an API is the set of guarantees about the product/service provided to the user.

Simply put, the remote control in question guarantees us to have an on/off button, two buttons to increase and decrease the volume, two buttons to switch to the previous and to the next channel.

Suppose the first implementation of the remote control doesn't have battery charge controls. When the charge is low, the remote control continues to work as long as you get close to the receiver. In the second implementation, the remote control stops working if the battery charge is less than 25%.

Even though these aspects are not covered by the contract, with a sufficiently large number of users, we will have the following scenario:

an user of the first implementation guesses that if the remote control doesn't work, he can approach the receiver to make it work. If the remote control continues not to work, then he must replace the batteries.

The same user, switching to the second implementation expects the same behavior. If the remote control doesn't work, he approaches the receiver to make it work. However, the remote control still doesn't work because in this case the implementation is based on the battery level and not the distance from the receiver. The user incorrectly concludes that the remote control or the receiver don’t work, but not that the batteries are dead.

That’s a case of Hyrum's Law: an API user is relying on an observable system behavior, even though the API contract doesn't guarantee it.

In software engineering, this law is also known as the "Law of implicit interfaces". It should be considered during the evolution of a system that needs to ensure backward compatibility. Both changes to the contract (explicit interface), and changes to other observable system behaviors (implicit interface) can break it.

The effects of this law can be mitigated in two ways: the API provider should limit exposure of observable system behaviors not described in the contract, and the user should rely only on the API contract. This makes it easier to introduce changes in a system.

https://www.hyrumslaw.com

Legge di Hyrum

Giovanni Gorgone — Thu, 02 Feb 2023 01:54:44 +0000

Stai facendo una modifica al codice, piccola, innocua. Ti fermi, sai che farai arrabbiare qualcuno. Mai provato questa sensazione? E’ esattamente ciò che prevede la legge di Hyrum:

“Non importa cosa espone un contratto,
dato un numero sufficientemente grande di utenti di un’API,
essi faranno affidamento su tutti gli aspetti osservabili del sistema esposto,
anche su quelli non esplicitati nel contratto stesso.”

Per comprenderla al meglio, analizziamo gli elementi coinvolti.

Cosa è un’API? Un’API è il confine tra utente e prodotto/servizio.

L’API di un telecomando della TV è composta dai suoi pulsanti. Essi vengono usati dagli utenti, i quali non han bisogno di sapere cosa succede all’interno del telecomando. Quel che succede all’interno del telecomando è chiamata “implementazione”. Qual’è il vantaggio di questa distinzione? Il vantaggio è che l’implementazione può cambiare senza che l’utente debba preoccuparsene.

Il contratto di un API è l’insieme di garanzie sul prodotto/servizio fornite all’utente.

Semplificando, il telecomando in questione ci garantisce di avere un pulsante di accensione e spegnimento, due pulsanti per aumentare e diminuire il volume, due pulsanti per passare al canale precedente e successivo.

Supponiamo che la prima implementazione del telecomando non abbia controlli sulla carica delle batterie. Quando la carica è bassa il telecomando continua a funzionare a patto che ci si avvicini alla ricevente. Nella seconda implementazione il telecomando smette di funzionare se la carica delle batterie è inferiore al 25%.

Anche se questi aspetti non rientrano nel contratto, con un numero sufficientemente grande di utenti, avremo il seguente scenario:

un utente della prima implementazione intuisce che se il telecomando non funziona, può avvicinarsi alla ricevente per farlo funzionare. Se il telecomando continua a non funzionare, allora deve sostituire le batterie.

Lo stesso utente, passando alla seconda implementazione si aspetta lo stesso comportamento. Se il telecomando non funziona si avvicina alla ricevente per farlo funzionare. Il telecomando però continua a non funzionare perché in questo caso l’implementazione è basata sul livello di carica e non sulla distanza dalla ricevente. L’utente conclude erroneamente che il telecomando o la ricevente non funzionino, ma non che le batterie siano scariche.

Siamo nell’ipotesi della legge di Hyrum: un utente di un’API sta facendo affidamento su un comportamento osservabile del sistema, anche se il contratto dell’API non da garanzie su di esso.

Nell’ambito dell’ingegneria del software questa legge è anche conosciuta come “Legge delle interfacce implicite”. E’ bene tenerla in considerazione durante l’evoluzione di un sistema che deve garantire retrocompatibilità. Infatti sia le modifiche al contratto (interfaccia esplicita), che quelle fatte agli altri comportamenti del sistema osservabili dagli utenti (interfaccia implicita) possono farla perdere.

E’ possibile mitigare gli effetti di questa legge in due modi: il fornitore di un API dovrebbe limitare l’esposizione di comportamenti osservabili del sistema non esplicitati nel contratto, e l’utente dovrebbe fare affidamento solo sul contratto dell’API. In questo modo sarà più facile introdurre cambiamenti in un sistema.

https://www.hyrumslaw.com

DEV Community: Giovanni Gorgone

Hyrum's law

Legge di Hyrum