[Python-ideas] Why is design-by-contracts not widely adopted?

[Brendan Barnwell]

On 2018-09-28 05:23, David Mertz wrote:
> On Thu, Sep 27, 2018, 9:25 PM Marko Ristin-Kaufmann
> <marko.ristin at gmail.com <mailto:marko.ristin at 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