为什么命令式语气对文档字符串很重要？

Question

pydocstyle的错误代码D401读取：First line should be in imperative mood。

我经常遇到以下情况：我写了一个文档字符串，当我的lint抛出了这个错误，然后重写了它，但是两个文档字符串在语义上是相同的。为什么对文档字符串有必要的态度很重要？

Answer 1

来自check_imperative_mood本身的文档字符串：

  """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 ...".

（（具有讽刺意味的是，该文档字符串本身将使测试失败。）

Answer 2

为什么重要？因为这是Python文档字符串的显式约定，如PEP 257中所述。它没有什么特别的地方-在我看来，“将两个整数相乘并返回乘积”和“将两个整数相乘并返回乘积”之一显然比另一个更好。但是它在文档中明确指定。

Answer 3

为了保持一致。可能是由于git自动创建的提交消息（如合并提交）也使用了命令性语气。