Why is imperative mood important for docstrings?

Question

The error code D401 for pydocstyle reads: First line should be in imperative mood.

I often run into cases where I write a docstring, have this error thrown by my linter, and rewrite it -- but the two docstrings are semantically identical. Why is it important to have imperative mood for docstrings?

Answer 1

From the docstring of check_imperative_mood itself:

  """D401: First line should be in imperative mood: 'Do', not 'Does'.

   [Docstring] prescribes the function or method's effect as a command:
    ("Do this", "Return that"), not as a description; e.g. don't write
    "Returns the pathname ...".

(We'll ignore the irony that this docstring itself would fail the test.)

Answer 2

Why is it important? Because that's the explicit convention for Python docstrings, as detailed in PEP 257. There's nothing particularly special about it - it doesn't seem obvious to me that one of "Multiplies two integers and returns the product" and "Multiply two integers and return the product" is clearly better than the other. But it is explicitly specified in the documentation.