Hello,<div><br></div><div>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&#39;ve always thought that a description in the indicative mood is appropriate. What&#39;s the point in saying it like a command? Who are you &quot;commanding&quot; when what you really want is to learn what the function/method does?</div>

<div><br></div><div>In Javadoc and XML doc (Java&#39;s and .NET&#39;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).</div>

<div><br></div><div>Is this difference somehow a corollary of the difference in programming paradigms?</div><div><br></div><div>Was there a discussion in <a href="mailto:doc-sig@python.org">doc-sig@python.org</a> about the reason(s) to use the imperative mood instead of the indicative mood, which then led to the recommendation in PEP 257?</div>

<div><br></div><div>Best Regards,</div><div>Kal</div>