imperative mood in docstrings

[bagrat lazaryan]

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

[Roy Smith]

In article <mailman.6584.1391950...@python.org>,

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.

[Mark Lawrence]

On 09/02/2014 12:05, 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?
>
> bagratte
>

I can't really answer your question as I don't understand why docstrings
should get moody, or did you mean mode? :)

--
My fellow Pythonistas, ask not what our language can do for you, ask
what you can do for our language.

Mark Lawrence

---
This email is free from viruses and malware because avast! Antivirus protection is active.
http://www.avast.com

[Jussi Piitulainen]

Mark Lawrence writes:
> On 09/02/2014 12:05, 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?
>

> I can't really answer your question as I don't understand why
> docstrings should get moody, or did you mean mode? :)

<http://en.wikipedia.org/wiki/Grammatical_mood>

[Chris “Kwpolska” Warrick]

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

[Ethan Furman]

On 02/09/2014 08:52 AM, Roy Smith wrote:
> In article <mailman.6584.1391950...@python.org>,
> bagrat lazaryan <bagr...@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~

[Terry Reedy]

On 2/9/2014 7:05 AM, 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?

The imperative is directed at the Python interpreter. It says what a
call instructs the interpreter to do.

--
Terry Jan Reedy

[Chris Angelico]

On Mon, Feb 10, 2014 at 4:53 AM, Ethan Furman <et...@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

[Steven D'Aprano]

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