On Mon, 12 Apr 2021 at 21:27, Brendan Barnwell <brenbarn@brenbarn.net> wrote:
On 2021-04-12 03:13, Stéfane Fermigier wrote:
The public API of a library is the one which is documented as such.
Right, except that in practice:
1) Many useful libraries are not documented or properly documented.
Then they're buggy. I'm not convinced by the argument that "in practice" people do things they shouldn't do and that therefore we should encourage them to do more of that.
A library can be useful and buggy at the same time or it can be useful but have some parts that are buggy and less useful. Ideally if some code is (potentially) useful but buggy then someone would come along and make it less buggy. If one of the deficiencies of the code to be improved is that it does not have a clear distinction between public and internal API then that task can be made much more difficult.
2) People don't read the docs (at least not always, and/or not in details).
Insofar as someone relies on behavior other than that given in the docs, they are being foolish. Again, I'm not convinced by the argument that "in practice" people do foolish things and that therefore we should encourage them to do more of that.
Maybe the docs were not so clear or maybe the library just has a lot of users or maybe some combination of the two. Either way it's much better for everyone involved if the code can be improved or extended without breaking things for people who are already using it. Standardising on simple practice that helps to make that happen is no bad thing. Oscar