Comment by mjw1007
1 year ago
Yes, the relationship between "Hyrum's Law" and having a terrible documentation culture is strong.
The important part of the "Law" is the bit where it says "it does not matter what you promise in the contract".
That's definitely going to be true in a place where neither writing nor reading documentation is taken seriously (and one of the main things this site teaches us is that Google is such a place).
Yeah, no, humans can't hold complicated documentation in their heads. The whole experience of being human is finding a way to get by with a simple model which fits in your head but isn't wrong enough to cause trouble, and that's exactly what Hyrum is reflecting.
What you're getting at is the C++ "Just don't make any mistakes" approach to software engineering, which is a disaster that has cost our civilisation a great deal.
That is emphatically not what I am "getting at". I cannot express my opposition to that approach strongly enough.
I do not believe that the place people should hold documentation is "in their heads".
I do not believe that Hyrum's "Law" is helpful in getting to a situation where people's beliefs about what software will do match reality.
This isn't the first time I've come across people (particularly around the Rust community) who have got the idea into their heads that saying "reading documentation is important" is somehow close to saying "Real programmers don't make mistakes". I think that conflation is doing great harm.
If you accept that people are going to rely on things you didn't contract for by mistake then you're right back to Hyrum's Law. It's that easy.
Hyrum's Law isn't about what you should do, or how things should be, it's telling you an observable fact about our world that some people don't like. So no, the law isn't going to fix people's beliefs any more than Newton's Laws did for weird beliefs about motion.
I'd actually say the importance of documentation is better understood in the Rust community. Including, which is vital here, the importance of not relying on humans remembering to read all this text when you've got better options. Rust has documentation telling you that you're not promised whether or not some elements which compare equal are swapped when you [T]::sort_unstable. But it doesn't need to spend a lot of time warning you that that you shouldn't [T]::sort_unstable a slice of type T which doesn't even claim to have ordering, because the compiler rejects such nonsense anyway.
Indeed even the naming is an example. In C++ that function is just named sort. Because you know, an unstable sort is faster†. Will it sometimes surprise some poor noob because it's unstable? Sure, but apparently that's OK because if they had read and properly digested the documentation they would know it's an unstable sort. I suggest if the function were named better the user is much less likely to make this mistake before they even glance at the documentation.
† Typically
3 replies →