imperative mood in docstrings

[Roy Smith]

In article <mailman.6584.1391950328.18130.python-list at python.org>,
 bagrat lazaryan <bagratte at 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.