verbs in comments [OT]

[Frederick Grose]

On Sat, Mar 24, 2012 at 4:24 PM, MRAB <python at mrabarnett.plus.com> wrote:

> On 24/03/2012 19:36, Kiuhnm wrote:
>
>> Why do you write
>>    // Print the number of words...
>>    def printNumWords(): ...
>> and not
>>    // Prints the number of words...
>>    def printNumWords(): ...
>> where "it" is understood?
>> Is that an imperative or a base form or something else?
>>
>>  The first is the imperative, the second is what it does (with the
> implied "it").
>
> Which form you use depends on what "feels" right.
>
> Probably what I'd do is use the first form where it's called and the
> second form where it's defined.
>
>    # Prints the number of words.
>    def print_num_words():
>       ...
>
>    # Print the number of words.
>    print_num_words()
>
> Although in this example the function is better written with a
> docstring, and the comment where the function is called doesn't add
> anything useful, so it's probably unnecessary.
>

PEP 257,
http://www.python.org/dev/peps/pep-0257/
notes,
"The docstring is a phrase ending in a period. It prescribes the function
or method's effect as a command ("Do this", "Return that"), not as a
description; e.g. don't write "Returns the pathname ..."."

         --Fred
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20120324/dee9dcdc/attachment-0001.html>