Path: csiph.com!usenet.pasdenom.info!weretis.net!feeder4.news.weretis.net!feeds.phibee-telecom.net!newsfeed.xs4all.nl!newsfeed2.news.xs4all.nl!xs4all!post.news.xs4all.nl!not-for-mail
MIME-Version: 1.0
In-Reply-To: <roy-94D93E.11521509022014@news.panix.com>
References: <mailman.6584.1391950328.18130.python-list@python.org> <roy-94D93E.11521509022014@news.panix.com>
Date: Sun, 9 Feb 2014 18:46:33 +0100
Subject: Re: imperative mood in docstrings
From: =?UTF-8?B?Q2hyaXMg4oCcS3dwb2xza2HigJ0gV2Fycmljaw==?= <kwpolska@gmail.com>
To: Roy Smith <roy@panix.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
Cc: python-list@python.org
Precedence: list
Newsgroups: comp.lang.python
Message-ID: <mailman.6597.1391968001.18130.python-list@python.org>
Lines: 44
NNTP-Posting-Host: 2001:888:2000:d::a6
Xref: csiph.com comp.lang.python:65775

On Sun, Feb 9, 2014 at 5:52 PM, Roy Smith <roy@panix.com> wrote:
> In article <mailman.6584.1391950328.18130.python-list@python.org>,
>  bagrat lazaryan <bagratte@live.com> wrote:
>
>> pep 257 -- docstring conventions, as well as a myriad of books and other
>> resources, recommend documenting a function's or method's effect as a co=
mmand
>> ("do this", "return that"), not as a description ("does this", "returns
>> that"). what's the logic behind this recommendation?
>>
>> bagratte
>
> Methods are verbs, and should be described as such.  If I had:
>
> class Sheep:
>    def fly(self):
>       "Plummet to the ground."
>
> I'm defining the action the verb performs.  If, on the other hand, I had:
>
> class Sheep:
>    def fly(self):
>       "Plummets to the ground"
>
> I'm no longer describing the action of flying, I'm describing what the
> sheep does when it attempts to perform that action.

This can also be seen with a (monolingual) dictionary.  For example:
https://www.google.com/search?q=3Ddefine+fly (that=E2=80=99s actually from =
the
New Oxford American Dictionary):

fly, verb: 1. move through the air under control. 2. move or be hurled
quickly through the air.

Those could be valid docstrings (if sheep could fly, of course=E2=80=A6) =
=E2=80=94 so,
in other words, act as if you were writing a dictionary and not Python
code.

--=20
Chris =E2=80=9CKwpolska=E2=80=9D Warrick <http://kwpolska.tk>
PGP: 5EAAEA16
stop html mail | always bottom-post | only UTF-8 makes sense