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 _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/