Path: csiph.com!usenet.pasdenom.info!aioe.org!news.stack.nl!newsfeed.xs4all.nl!newsfeed4a.news.xs4all.nl!xs4all!post.news.xs4all.nl!not-for-mail
Return-Path: <ethan@stoneleaf.us>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.003
X-Spam-Evidence: '*H*': 0.99; '*S*': 0.00; 'else:': 0.03; 'from:addr:ethan': 0.09; 'from:addr:stoneleaf.us': 0.09; 'from:name:ethan furman': 0.09; 'if,': 0.09; 'logic': 0.09; 'message-id:@stoneleaf.us': 0.09; 'pep': 0.09; '~ethan~': 0.09; 'def': 0.12; 'books': 0.15; 'be:': 0.16; 'docstring': 0.16; "function's": 0.16; "method's": 0.16; 'received:70.85.130': 0.16; 'roy': 0.16; 'wrote:': 0.18; 'command': 0.22; 'header:User- Agent:1': 0.23; "shouldn't": 0.24; 'header:In-Reply-To:1': 0.27; 'am,': 0.29; "i'm": 0.30; 'documenting': 0.31; 'such.': 0.31; 'class': 0.32; 'described': 0.36; 'charset:us-ascii': 0.36; 'should': 0.36; 'behind': 0.37; 'to:addr:python-list': 0.38; 'to:addr:python.org': 0.39; 'received:173': 0.61; 'air': 0.66; 'smith': 0.68; 'article': 0.77; '257': 0.84; 'performs.': 0.84; 'hand,': 0.93; 'hot': 0.96
Date: Sun, 09 Feb 2014 09:53:27 -0800
From: Ethan Furman <ethan@stoneleaf.us>
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:16.0) Gecko/20121010 Thunderbird/16.0.1
MIME-Version: 1.0
To: python-list@python.org
Subject: Re: imperative mood in docstrings
References: <mailman.6584.1391950328.18130.python-list@python.org> <roy-94D93E.11521509022014@news.panix.com>
In-Reply-To: <roy-94D93E.11521509022014@news.panix.com>
Content-Type: text/plain; charset=us-ascii; format=flowed
Content-Transfer-Encoding: 7bit
X-AntiAbuse: This header was added to track abuse, please include it with any abuse report
X-AntiAbuse: Primary Hostname - gator3304.hostgator.com
X-AntiAbuse: Original Domain - python.org
X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12]
X-AntiAbuse: Sender Address Domain - stoneleaf.us
X-BWhitelist: no
X-Source-IP: 173.12.184.233
X-Source: 
X-Source-Args: 
X-Source-Dir: 
X-Source-Sender: ([173.12.184.233]) [173.12.184.233]:52744
X-Source-Auth: ethan+stoneleaf.us
X-Email-Count: 1
X-Source-Cap: dG9idWs7dG9idWs7Z2F0b3IzMzA0Lmhvc3RnYXRvci5jb20=
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.15
Precedence: list
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <https://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: <https://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.6598.1391969791.18130.python-list@python.org>
Lines: 35
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1391969791 news.xs4all.nl 2862 [2001:888:2000:d::a6]:44217
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:65776

On 02/09/2014 08:52 AM, Roy Smith 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 command
>> ("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:

Shouldn't that be:

   class Pig:
       def fly(self):
       "Soar gracefully through the air if a hot place is very cold."
           if hell is frozen:
               self.sprout_wings()
               self.altitude += 10
               self.velocity += 25
           else:
               self.splat()

;)

--
~Ethan~