imperative mood in docstrings

[Chris “Kwpolska” Warrick]

On Sun, Feb 9, 2014 at 5:52 PM, Roy Smith <roy at panix.com> 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:
>
> 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.

-- 
Chris “Kwpolska” Warrick <http://kwpolska.tk>
PGP: 5EAAEA16
stop html mail | always bottom-post | only UTF-8 makes sense