如何编写有意义的文档字符串？

Posted 2023-02-21

【中文标题】如何编写有意义的文档字符串？

【英文标题】：How to write meaningful docstrings?

【发布时间】：2010-10-10 18:08:18

【问题描述】：

您认为什么是有意义的文档字符串？你希望在那里被描述什么？

例如，考虑这个 Python 类的__init__：

def __init__(self, name, value, displayName=None, matchingRule="strict"):
    """
    name - field name
    value - field value
    displayName - nice display name, if empty will be set to field name
    matchingRule - I have no idea what this does, set to strict by default
    """

你觉得这有意义吗？发布您的好/坏示例以供所有人了解（以及一般性答案，以便可以接受）。

【参考方案1】：

我同意“从方法的签名中无法分辨的任何内容”。这也可能意味着解释方法/函数返回什么。

您可能还想在您的文档字符串中使用Sphinx（和reStructuredText 语法）来记录文档。这样您就可以轻松地将其包含在您的文档中。例如，请查看例如repoze.bfg 广泛使用它（example file，documentation example）。

另一个可以放入文档字符串的东西也是doctests。这可能是有道理的，尤其是。对于模块或类文档字符串，您还可以展示如何使用它并同时使其可测试。

【讨论】：

使用doctests 是一个很好的建议。有意义的例子不仅可以向用户展示如何处理边缘情况，同时如果对代码的任何更改改变了预期的行为，也会向您发出警告。您还可以在每次发现错误时扩展这些示例，以确保它不会再次蔓延到您身上，或者至少在未纠正时警告该错误的存在。

【参考方案2】：

来自PEP 8：

编写良好文档字符串的约定（a.k.a. "docstrings") 在PEP 257 中永垂不朽。

为所有公共模块、函数、类和方法编写文档字符串。非公共方法不需要文档字符串，但你 应该有一个注释来描述该方法的作用。这 注释应出现在“def”行之后。 PEP 257 描述了良好的文档字符串约定。请注意，最重要的是，结束多行文档字符串的 """ 应该位于 单独一行，最好在前面有一个空行。 对于单行文档字符串，可以将结尾的 """ 保持在同一行。

【讨论】：

这似乎涵盖了语法而不是语义。也许有人们喜欢的首选风格？您是否尝试在文档字符串中填写所有 @foobr 关键字？

Xolve 真的应该发布 PEP 257 的链接：python.org/dev/peps/pep-0257

【参考方案3】：

查看 numpy 的文档字符串以获得好的示例（例如 http://github.com/numpy/numpy/blob/master/numpy/core/numeric.py）。

文档字符串被分成几个部分，如下所示：

Compute the sum of the elements of a list.

Parameters
----------
foo: sequence of ints
   The list of integers to sum up.

Returns
-------
res: int
   sum of elements of foo

See also
--------
cumsum:  compute cumulative sum of elemenents

【参考方案4】：

应该去那里：

从方法的签名中无法分辨的任何内容。在这种情况下，唯一有用的是：displayName - 如果为空，将设置为字段名称。

【讨论】：

+1 表示“从方法的签名中无法分辨的任何内容”

epydoc 和 sphinx 项目中应该包含的具体信息。见epydoc.sourceforge.net/epydoc.html

【参考方案5】：

我能想到包含在文档字符串中的最引人注目的东西是不明显的东西。通常这包括类型信息或能力要求 - 例如。 “需要一个类似文件的对象”。在某些情况下，这可以从签名中明显看出，而在其他情况下则不然。

您可以在文档字符串中添加的另一个有用的东西是doctest。

【参考方案6】：

我喜欢使用文档尽可能详细地描述函数的作用，尤其是在极端情况（也称为边缘情况）下的行为。理想情况下，使用该函数的程序员永远不必查看源代码 - 实际上，这意味着每当另一个程序员确实必须查看源代码以了解该函数如何工作的一些细节时，该细节可能应该是文档中提到。正如 Freddy 所说，任何不向方法签名添加任何细节的东西都可能不应该出现在文档字符串中。

【参考方案7】：

在函数开头添加doc string的一般目的是描述函数，它做什么，它会返回什么，以及关于参数的描述。如果需要，您可以添加实施细节。甚至您可以添加有关为未来开发人员编写代码的作者的详细信息。