[Tutor] Prescriptive vs descriptive docstring

[Steven D'Aprano]

Kal Sze wrote:
> Hello,
> 
> PEP 257 says that docstrings should be written in a prescriptive way (i.e.
> using the imperative mood) instead of a descriptive way (indicative mood).

PEP 257: http://www.python.org/dev/peps/pep-0257/

For those who don't know English grammatical terms, here are some examples.


Imperative mood:

- "Return the number of widgets in a set."
- "Control access to the phlebotinum."
- "Set the printer on fire."


Indicative mood:

- "[This function] returns the number of widgets in a set."
- "[This class] controls access to the phlebotinum."
- "[This method] sets the printer on fire."


> This seems like a rather odd recommendation. Since the docstring is
> supposed to tell the programmer *how* to use a function/method, I've always
> thought that a description in the indicative mood is appropriate. What's
> the point in saying it like a command? Who are you "commanding" when what
> you really want is to learn what the function/method does?

"You" is the person writing the doc string, that is, the person writing the 
code (or someone working on her behalf). So the imperative mood is commanding 
the computer: "Method, you will set the printer on fire."

If I had to guess a reason why this convention exists, it would be that some 
people don't like implying the subject of the imperative mood, or think it is 
ungrammatical to say "Sets the printer on fire" without stating who or what 
sets the printer on fire. But it gets tiresome very, very quickly to preface 
every doc string with "This function...", "This method..." etc.

But as I said, that's a guess.


> In Javadoc and XML doc (Java's and .NET's equivalent to docstrings), the
> de-facto convention is to use the indicative mood (as can be seen in the
> whole standard java class library and .net class library).
> 
> Is this difference somehow a corollary of the difference in programming
> paradigms?

I doubt it. I suspect it was just somebody's personal preference.

Personally, I don't pay too much attention to PEP 257. Some attention, but I 
don't follow it slavishly. And neither does the standard library -- for 
example, the decimal module has a mix of imperative and indicative mood in the 
doc strings.

In any case, unless you are writing for the Python standard library, nobody 
can force you to follow PEP 257. It may be *recommended*, but you are free to 
ignore it, and take the consequences.



> Was there a discussion in doc-sig at python.org about the reason(s) to use the
> imperative mood instead of the indicative mood, which then led to the
> recommendation in PEP 257?

You would be better off asking on doc-sig@ or python-dev at python.org.



-- 
Steven