[Tutor] Prescriptive vs descriptive docstring
steve at pearwood.info
Sat May 12 04:21:11 CEST 2012
Kal Sze wrote:
> 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.
- "Return the number of widgets in a set."
- "Control access to the phlebotinum."
- "Set the printer on fire."
- "[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
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
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.
More information about the Tutor