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