非命令语气 (D401)

源自 pydocstyle 代码检查器。

作用

检查文档字符串的第一行是否为命令语气。

为什么这不好？

PEP 257 建议为了保持一致性，文档字符串的第一行应以命令语气书写。

提示：要以命令语气重写文档字符串，请将第一行表达得像一条命令。

此规则可能不适用于所有项目；其适用性是一个惯例问题。默认情况下，当使用 numpy 和 pep257 约定启用此规则，而当使用 google 约定则禁用此规则。

示例

def average(values: list[float]) -> float:
    """Returns the mean of the given values."""

建议改为

def average(values: list[float]) -> float:
    """Return the mean of the given values."""

Options (选项)

• lint.pydocstyle.convention
• lint.pydocstyle.property-decorators
• lint.pydocstyle.ignore-decorators

参考

• PEP 257 – 文档字符串约定