verbs in comments [OT]

Jean-Michel Pichavant jeanmichel at sequans.com
Mon Mar 26 14:36:19 CEST 2012


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?
>
> Kiuhnm

http://www.python.org/dev/peps/pep-0257/

"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 ..."

I apply the same rule to comments, I now don't loose time asking myself 
how to write these docs/comments.

JM



More information about the Python-list mailing list