On 23/09/2013 20:01, Terry Reedy wrote:
On 9/22/2013 10:44 PM, Guido van Rossum wrote:
Glad you like it. I still do, too, but I've given up hope to convince all core developers to stick to this style. :-(
[me] ('Return' rather than 'Returns' is the current convention.)
That's actually a religious argument which in the stdlib takes no strict position -- a quick grep shows that both are used, although 'Return' is more frequent by a 5-to-1 margin.
In the .rst docs, 'Return' versus 'Returns', exact uppercase word match, is a little over 3 to 1. I am sure I have seen 'Return' and similiar directive forms ('Print', 'Store', 'Compare', etc) recommended as current doc style, as prefered by the current doc crew.
IIRC in the Java world you *have* to use 'Returns', but I don't buy the argument from nit-picky grammarians that leads to this rule. (It's something about the documentation not being a command. But English is more flexible than that.)
My take is that 'Returns' describes to the programmer what the function (interpreter) does, while 'Return' says what the programmer says to the interpreter when using the function. I strongly prefer the directive form. Why? For one thing, *because* it is different from normal descriptive text, such as the first sentence of this paragraph. For another, the descriptive form seems addressed to me as code reader while the directive form seems addressed to me as code writer. For me, the latter seems more energizing.
<pedantic>I think you mean "imperative" vs "indicative".</pedantic>