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>
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4