imperative mood in docstrings

[Steven D'Aprano]

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