On Thu, Sep 27, 2018 at 3:31 PM Greg Ewing <greg.ew...@canterbury.ac.nz> wrote: > > Chris Angelico wrote: > > if you let your API > > docs rot when you make changes that callers need to be aware of, you > > have failed your callers. > > Yes, I find that documentation auto-generated from code is > usually a poor substitute for human-written documentation. > Dumping your formally-written contracts into the docs makes > the reader reverse-engineer them to figure out what the > programmer was really trying to say. > > Which do you find easier to grok at a glance: > > all(L[i] <= L[i+1] for i in range(len(L) - 1)) > > or > > # The list is now sorted >
Well, with that particular example, you're capitalizing on the known meaning of the English word "sorted". So to be fair, you should do the same in Python: postcondition: L == sorted(L) This would be inappropriate for an actual sorting function, but let's say you're altering the value of an item in a sorted list, and shifting it within that list to get it to the new position, or something like that.python-ideas <python-ideas@python.org> But yes, in general I do agree: it's frequently cleaner to use an English word than to craft a Python equivalent. ChrisA _______________________________________________ Python-ideas mailing list Python-ideas@python.org https://mail.python.org/mailman/listinfo/python-ideas Code of Conduct: http://python.org/psf/codeofconduct/
