Comment by Someone
11 hours ago
> That doesn't mean there's a problem with the code, only with the documentation.
I disagree. If the obvious way to use an API is the incorrect way, there is a problem with the code.
If you must call A each time before calling B, drop A and have B do both things.
If you must call A once before calling B, make A return a token that you then must pass to B to show you called A.
As another example, look at https://news.ycombinator.com/item?id=47060334):
“Two popular AES libraries, aes-js and pyaes, “helpfully” provide a default IV in their AES-CTR API, leading to a large number of key/IV reuse bugs. These bugs potentially affect thousands of downstream projects.”
Would you call that “poor code style that could theoretically lead to a bug in the future”, too?
The API in question is almost certainly internal. The only reason it isn’t marked as such is because Python doesn’t have great facilities for that kind of encapsulation.
Invariant-preserving types are always going to be the right way to eliminate certain classes of bugs, but they’re also completely overkill in this context given that the “bug” in question doesn’t even cause unsound program behavior; it just raises an exception, which is completely sound and well-defined.
[dead]