Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #65776

Re: imperative mood in docstrings

Show all headers | View raw

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~

Back to comp.lang.python | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

imperative mood in docstrings bagrat lazaryan <bagratte@live.com> - 2014-02-09 16:05 +0400
  Re: imperative mood in docstrings Roy Smith <roy@panix.com> - 2014-02-09 11:52 -0500
    Re: imperative mood in docstrings Chris “Kwpolska” Warrick <kwpolska@gmail.com> - 2014-02-09 18:46 +0100
    Re: imperative mood in docstrings Ethan Furman <ethan@stoneleaf.us> - 2014-02-09 09:53 -0800
    Re: imperative mood in docstrings Chris Angelico <rosuav@gmail.com> - 2014-02-10 09:12 +1100
  Re: imperative mood in docstrings Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2014-02-09 23:01 +0000

csiph-web