Hyrum's law
expressãoprogramação
Com usuários suficientes, todo comportamento observável do seu sistema será dependido por alguém, com contrato ou sem.
Cunhada pelo engenheiro do Google Hyrum Wright, a lei explica por que 'nunca prometemos isso' não evita quebras: usuários se prendem a tempos, textos de erro, ordenação e manias não documentadas, então a interface de facto é tudo que é observável. O xkcd 1172 ('toda mudança quebra o fluxo de trabalho de alguém') é sua forma em quadrinhos. É a razão profunda pela qual refatorações que preservam comportamento ainda acordam alguém às 3 da manhã.
Com um número suficiente de usuários, todo comportamento observável do seu sistema será usado como dependência por alguém, independentemente do que você prometeu no contrato. A observação de Hyrum Wright é que a interface documentada e a interface que você de fato tem são coisas diferentes, e a segunda é maior.
As consequências são contraintuitivas. Corrigir um defeito pode quebrar usuários que o contornavam. Deixar algo mais rápido pode quebrar quem dependia do tempo anterior. Mudar a ordem dos resultados de uma coleção não ordenada quebra quem supôs que a ordem era estável, e essa suposição estava errada, e o código funcionava até você mudar. O texto de uma mensagem de erro vira API no instante em que alguém o interpreta.
As respostas práticas tratam de reduzir a observabilidade, e não de reforçar a documentação, porque documentação não restringe o que as pessoas fazem. Aleatorizar deliberadamente o que é genuinamente não ordenado impede a dependência de se formar. Versionamento permite que o comportamento antigo persista para quem precisa. E em escala suficiente a posição honesta é que não dá para consertar tudo, então você escolhe quais quebras aceitar e as comunica, que é atividade muito diferente de acreditar que seu contrato o protege.