On 2018-09-28 05:23, David Mertz wrote:
On Thu, Sep 27, 2018, 9:25 PM Marko Ristin-Kaufmann
<marko.ris...@gmail.com <mailto:marko.ris...@gmail.com>> wrote:
Try to question whether the contracts I wrote are so obvious to
everybody even if they are obvious to you and keep in mind that the
user does not look into the implementation.
I had missed this comment, but this seems to be the biggest disconnect,
or talking past each other.
I'm a user of many libraries. I USUALLY look at the implementation when
in doubt about a function. If contracts are meant only for users who
don't look at code, the detrimental effect on code readability is mitigated.
I agree with you that this seems to be a major disconnect in the
discussion here. However, on the issue itself, I quite agree with Marko
that it is *much* more important for the documentation to be readable
than for the function to be readable. I too read the source of
functions sometimes, and whenever I find myself having to do so, I
grouse at the authors of whatever libraries I'm using for not making the
documentation more clear. Ideally, no user should *ever* have to read
the function source code, because the documentation should make it
completely clear how to use the function without knowing *anything*
about how it is implemented.
Of course, this ideal will never be achieved, but I think it's
something to aim towards, and the idea that adding a few lines of DbC
decorators makes the source code too cluttered seems quite incorrect to
me. I glanced through the source code and didn't find it hard to read
at all. The contracts are all cleanly separated from the function
bodies because they're in decorators up front. I'm frankly quite
baffled that other people on this thread find that hard to read.
The problem with reading the source code is that you can't tell what
parts of the behavior are specified and which are implementation
details. The appeal of something like DbC is that it encourages (some
might say painfully forces) programmers to be very explicit about what
behavior they want to guarantee.
Whether writing these guarantees as Python expressions is better than
writing them as prose is another matter. Personally I do see some value
in the modifications that Marko made to pathlib. In a sense, writing
"documentation as Python code" is like annotating the source code to
mark which specific parts of the implementation are guarantees and which
may be implementation details. I think there is significant value in
knowing precisely what an API allows, in an explicit and verifiable form
such as that provided by DbC, rather than using human language, which is
much less precise, can leave room for misinterpretation, and, perhaps
most importantly, is harder to verify automatically.
Ultimately, I'm firmly of the opinion that, in publicly distributed
code, the function *IS* its documentation, not its source code. When a
function's actual behavior conflicts with its documented behavior, that
is a bug. When meaningful aspects of a functions behavior are not
specified in the documentation, that is also a bug. These may be bugs in
the documentation or in the behavior, but either way the point is that
reading the source code is not an acceptable substitute for making the
documentation a complete and self-sufficient vehicle for total
understanding of the function's behavior. It doesn't matter if the
function behaves as the author intended; it only matters if it behaves
as documented.
--
Brendan Barnwell
"Do not follow where the path may lead. Go, instead, where there is no
path, and leave a trail."
--author unknown
_______________________________________________
Python-ideas mailing list
Python-ideas@python.org
https://mail.python.org/mailman/listinfo/python-ideas
Code of Conduct: http://python.org/psf/codeofconduct/
