[Tutor] Prescriptive vs descriptive docstring

[Kal Sze]

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).
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
paradigms?

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?

Best Regards,
Kal
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/tutor/attachments/20120511/c1ca0d3d/attachment.html>