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-...@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-...@python.org.
--
Steven
_______________________________________________
Tutor maillist - Tutor@python.org
To unsubscribe or change subscription options:
http://mail.python.org/mailman/listinfo/tutor
