31

在您看来，什么是有意义的文档字符串？你期望在那里被描述什么？

例如，考虑这个 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
    """

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

4

7 回答 7

16

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

您可能还希望使用Sphinx（和 reStructuredText 语法）在您的文档字符串中进行文档编制。这样您就可以轻松地将其包含在您的文档中。例如，请查看广泛使用此功能的repoze.bfg （示例文件、文档示例）。

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

于 2009-03-02T11:25:15.397 回答
9

从PEP 8开始：

编写好的文档字符串（又名“文档字符串”）的约定在PEP 257中得到了永生。

  • 为所有公共模块、函数、类和方法编写文档字符串。非公共方法不需要文档字符串，但您应该有一个注释来描述该方法的作用。此注释应出现在“def”行之后。
  • PEP 257描述了良好的文档字符串约定。请注意，最重要的是，结束多行文档字符串的 """ 应该单独一行，并且最好在前面有一个空行。
  • 对于一个班轮文档字符串，可以将结束的 """ 保持在同一行。
于 2009-03-02T12:51:32.177 回答
7

查看 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
于 2011-01-14T10:56:25.690 回答
6

应该去那里：

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

于 2009-03-02T10:44:16.540 回答
2

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

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

于 2009-03-02T12:34:34.123 回答
1

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

于 2009-03-02T11:06:44.707 回答
0

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

于 2017-02-24T17:05:20.530 回答