imperative mood in docstrings

Sun Feb 9 11:52:15 EST 2014

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.