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>
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
