imperative mood in docstrings

Sun Feb 9 12:53:27 EST 2014

On 02/09/2014 08:52 AM, Roy Smith wrote:
> 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:

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~