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

StackOverflow https://stackoverflow.com/questions/601900

  •  03-07-2019
  •  | 
  •  

题

什么，你的意见是一个有意义的文档字符串?你能指望什么被描述的那里？

例如，可以考虑这蟒蛇类 __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
    """

你觉得这个有意义？后你的好坏的例子所有人都知道(和一个一般性的答案，所以它可以被接受)。

有帮助吗？

解决方案

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

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

可以在docstrings中添加的另一件事也是 doctests 。这可能是有道理的。对于模块或类文档字符串，您也可以显示如何使用它并同时测试它。

其他提示

从 PEP8:

约书写好文件串(a。k.a."文档字符串")是不朽的 PEP257.

  • 写文档字符串的所有公共模块的功能、类和方法。文档字符串是没有必要为非公开的方法，但是你 应该有一个注释，说明什么方法。此 评论应当出现在"清晰度"的路线。
  • PEP257 描述了很好的文档字符串的公约。注意，最重要的是，"""结束一个多文档字符串应该是在 行，并优先通过一个空行。
  • 对于一个衬垫文档字符串的，没事的保持封闭"""在同一条线上。

应该去哪里：

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

查看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

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

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

我喜欢使用文档尽可能详细地描述函数的功能，特别是角点情况下的行为（a.k.a.边缘情况）。理想情况下，使用该函数的程序员永远不必查看源代码 - 实际上，这意味着每当另一个程序员必须查看源代码以找出函数如何工作的一些细节时，该细节可能应该是在文档中提到。正如Freddy所说，任何不对方法签名添加任何细节的内容都可能不应该在文档字符串中。

通常在函数启动时添加添加文档字符串的目的是描述函数，它的作用，返回的内容以及参数的描述。您可以根据需要添加实施细节。即使您可以添加有关为未来开发人员编写代码的作者的详细信息。

许可以下： CC-BY-SA 和 归因
不隶属于 StackOverflow
scroll top