[Python-ideas] Pre-conditions and post-conditions

[Steven D'Aprano]

On Tue, Sep 04, 2018 at 10:50:27AM +1200, Greg Ewing wrote:
> Jonathan Fine wrote:
> >I've just read and article which makes a good case for providing 
> >pre-conditions and post-conditions.
> >
> >http://pgbovine.net/python-unreadable.htm
> 
> There's nothing in there that talks about PBC-style executable
> preconditions and postconditions, it's all about documenting
> the large-scale intent and purpose of code.

Indeed. Apart from a throw-away comment about using pre-conditions and 
post-conditions, that post has little or nothing to do with contracts 
specifically.


> He doesn't put
> forward any argument why executable code should be a better
> way to do that than writing comments.

That's because the article isn't about executable comments versus dumb 
comments. Its about the need for writing documentation and comments of 
any sort, so long as it helps people understand the purpose of the code, 
what and why it does what it does.

If you read the author's other posts, he discusses the advantages of 
assertions over dumb comments in other places, such as here:

http://pgbovine.net/programming-with-asserts.htm

As far as dumb comments go, I'm reminded of this quote:

    "At Resolver we've found it useful to short-circuit any 
    doubt and just refer to comments in code as 'lies'."

    --Michael Foord paraphrases Christian Muirhead
      on python-dev, 2009-03-22


But you're right that assertions can only give you limited assistence in 
understanding the large scale structure of code:

- types tell you only what kind of thing a variable is;

- assertions tell you both the kind of thing and the acceptible
  values it can take;

- unlike dumb comments, assertions are checked, so they stay 
  relevant longer and are less likely to become lies.

These can help the reader understand the what and sometimes the how, but 
to understand the why you need to either be able to infer it from the 
code, or documentation (including comments).

Given the choice between a comment and an assertion:

    # x must be between 11 and 17
    assert 11 <= x <= 17

I think it should be obvious why the assertion is better. But neither 
explain *why* x must be within that range. Unless it is obvious from 
context (and often it is!) there should be a reason given, otherwise the 
reader has to just take it on faith.


> Personally I don't think it is. E.g.
> 
>     def distim(doshes):
>        for d in doshes:
>            assert isinstance(d, Dosh)
>        # do something here
>        for d in doshes:
>            assert is_distimmed(d)
> 
> This ticks the precondition and postcondition boxes, but
> still doesn't give you any idea what a Dosh is and why
> you would want to distim it.

I think the author would agree with you 100%, given that his article is 
talking about the need to understand the *why* of code, not just what it 
does in small detail, but the large scale reasons for it.



-- 
Steve