On Thu, Sep 27, 2018 at 3:31 PM Greg Ewing email@example.com 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))
# 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 firstname.lastname@example.org
But yes, in general I do agree: it's frequently cleaner to use an English word than to craft a Python equivalent.