Path: csiph.com!usenet.pasdenom.info!aioe.org!news.stack.nl!newsfeed.xs4all.nl!newsfeed5.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail
Return-Path: <prvs=42574d81d=jeanmichel@sequans.com>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.090
X-Spam-Evidence: '*H*': 0.83; '*S*': 0.01; 'url:peps': 0.09; 'sfxlen:2': 0.11; 'print': 0.15; 'cc:addr:python-list': 0.15; 'def': 0.20; 'wrote:': 0.21; 'function': 0.22; 'url:dev': 0.22; 'header:In-Reply-To:1': 0.22; '"the': 0.23; 'header:User-Agent:1': 0.23; 'cc:no real name:2**0': 0.26; 'cc:addr:python.org': 0.27; 'command': 0.28; 'rule': 0.29; 'subject: [': 0.29; 'asking': 0.29; 'cc:2**0': 0.31; 'url:python': 0.34; 'why': 0.36; 'url:org': 0.36; 'something': 0.38; 'base': 0.39; 'how': 0.40; 'header:Received:2': 0.63; 'received:194': 0.72; 'docstring': 0.84; 'phrase': 0.84; 'loose': 0.91; 'period.': 0.95
X-IronPort-AV: E=Sophos;i="4.75,320,1330902000"; d="scan'208";a="276135"
X-Virus-Scanned: amavisd-new at zimbra.sequans.com
Date: Mon, 26 Mar 2012 14:36:19 +0200
From: Jean-Michel Pichavant <jeanmichel@sequans.com>
User-Agent: Mozilla-Thunderbird 2.0.0.24 (X11/20100328)
MIME-Version: 1.0
To: Kiuhnm <kiuhnm03.4t.yahoo.it@mail.python.org>
Subject: Re: verbs in comments [OT]
References: <4f6e2265$0$1382$4fafbaef@reader2.news.tin.it>
In-Reply-To: <4f6e2265$0$1382$4fafbaef@reader2.news.tin.it>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Cc: python-list@python.org
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.12
Precedence: list
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <http://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <http://mail.python.org/pipermail/python-list>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <http://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.998.1332765381.3037.python-list@python.org>
Lines: 22
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1332765381 news.xs4all.nl 6935 [2001:888:2000:d::a6]:34250
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:22185

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