[Tutor] Prescriptive vs descriptive docstring
swordangel at gmail.com
Fri May 11 05:41:45 CEST 2012
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).
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?
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
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?
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Tutor