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

Groups > comp.lang.python > #65753 > unrolled thread

imperative mood in docstrings

Back to article view | Back to comp.lang.python

Contents

  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

#65753 — imperative mood in docstrings

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

[toc] | [next] | [standalone]

#65771

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:

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.

[toc] | [prev] | [next] | [standalone]

#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 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:
>
> 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=define+fly (that’s 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…) — so,
in other words, act as if you were writing a dictionary and not Python
code.

-- 
Chris “Kwpolska” Warrick <http://kwpolska.tk>
PGP: 5EAAEA16
stop html mail | always bottom-post | only UTF-8 makes sense

[toc] | [prev] | [next] | [standalone]

#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~

[toc] | [prev] | [next] | [standalone]

#65784

On Mon, Feb 10, 2014 at 4:53 AM, Ethan Furman <ethan@stoneleaf.us> wrote:
> 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()
>
> ;)

The Python 'is' operator does not do what you think it does. If it
did, 'hell is frozen' would mean that one could say 'war is frozen',
which makes no sense. No, I think this calls for a LISP-style
predicate:

if frozenp(hell):

ChrisA

[toc] | [prev] | [next] | [standalone]

#65786

On Sun, 09 Feb 2014 16:05:59 +0400, bagrat lazaryan 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?

Consider a class with a procedural method, that is, a method that does 
something:

class Duck:
    def swim(self):
        """Flap feet in a rhythmic manner so as to gracefully move
        through water.
        """

Here, we naturally write as if giving instructions to the duck, that is, 
using the imperative mood. "Duck, swim."

From there, it isn't a big step to using the same mood for functions:

def count(haystack, needle):
    """Return the number of needles in haystack."""

Here we are figuratively instructing the function, telling it what to do:

"Function, return the number of needles found in this haystack."



-- 
Steven

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web