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]

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.

 

[Chris “Kwpolska†Warrick]

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.

 

[Ethan Furman]

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()

 

[Chris Angelico]

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]

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."