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

Question

对于pydocstyle错误代码D401阅读：First line should be in imperative mood。

我经常遇到这样的情况，我写了一个文档字符串，我的 linter 抛出了这个错误，然后重写了它——但这两个文档字符串在语义上是相同的。为什么对 docstrings 有必要的情绪很重要？

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

在一个项目或一个公司内保持一致的风格更为重要。

\n

整个想法来自PEP-257，它说

\n

\n

文档字符串是一个以句点结尾的短语。它将\n函数或方法\xe2\x80\x99s 的效果规定为命令（\xe2\x80\x9c执行此操作\xe2\x80\x9d、\xe2\x80\x9c返回\xe2\x80\x9d），\n不作为说明; 例如，不要\xe2\x80\x99t 写入\xe2\x80\x9c，返回路径名\xe2\x80\xa6\xe2\x80\x9d。

\n

\n

但例如Google Python 风格指南的说法与此完全相反：

\n

\n

文档字符串应该是描述性风格（"""从\nBigtable 获取行。"""）而不是命令式（"""从\nBigtable 获取行。"""）。

\n

\n

更新（2023）：从那时起，Google 风格指南发生了变化。现在它允许两种样式而无需明确的偏好：

\n

\n

文档字符串可以是描述性风格（"""从 Bigtable 中获取行。"""）或命令式风格（"""从 Bigtable 中获取行。"""），\n但是风格应该在文件。

\n

\n

还值得一提的是，Oracle Java 风格指南和 Microsoft .NET 指南都更喜欢描述性风格。

\n

\n

使用第三人称（描述性）而不是第二人称（规定性）。

\n

描述采用第三人称陈述式而不是第二人称\n命令式。

\n

获取标签。（首选）

\n

获取标签。（避免）

\n

\n

所以看起来这种命令式风格的偏好是 Python 特有的。

\n

Answer 3

仅仅说它是关于约定或一致性是不完整的（否则，后续问题将是“与什么一致？”）。

它实际上是规范PEP 257 文档字符串约定中的一项明确要求，尽管它深藏其中。引述如下：

def kos_root():
    """Return the pathname of the KOS root directory."""
    ...

笔记：

• 文档字符串是一个以句点结尾的短语。它将函数或方法的效果规定为命令（“执行此操作”、“返回该操作”），而不是描述；例如，不要写“返回路径名...”。

该 pydocstyle 文档字符串实际上引用自上面的 PEP 257 段落。

Answer 4

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

Answer 5

考虑以下文档字符串的候选示例：

Make a row from a given bit string or with the given number of columns.

在英语中，这是一个完整的语法句子，以大写字母开头并以句点结尾。这是一个句子，因为它有一个主语（隐式为“你”）、一个宾语“行”和一个谓词（动词）“make”。

现在考虑一个替代方案：

Makes a row from a given bit string or with the given number of columns.

在英语中，这是不合语法的。它是形容词短语，因此不应以大写字母开头，不应以句点结尾。让我们解决这个问题：

makes a row from a given bit string or with the given number of columns

作为形容词短语，它的先行词——它的目标——并不明确。当然，我们知道它是“文档字符串化”的项目，但是，从语法上讲，它是悬空的。这是个问题。从美学上讲，它很丑陋，这是另一个问题。所以我们解决了一个问题，又增加了两个。

对于关心语法英语清晰、模棱两可的交流的人来说，第一个建议显然更胜一筹。我猜这就是 Pythonistas 选择第一个提案的原因。总之，“文档字符串应该是完整的、符合语法的句子，特别是在祈使语气中。”