题
什么,你的意见是一个有意义的文档字符串?你能指望什么被描述的那里?
例如,可以考虑这蟒蛇类 __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 。这可能是有道理的。对于模块或类文档字符串,您也可以显示如何使用它并同时测试它。
其他提示
应该去哪里:
你从方法的签名中无法分辨的任何东西。在这种情况下,唯一有用的是: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所说,任何不对方法签名添加任何细节的内容都可能不应该在文档字符串中。
通常在函数启动时添加添加文档字符串的目的是描述函数,它的作用,返回的内容以及参数的描述。您可以根据需要添加实施细节。即使您可以添加有关为未来开发人员编写代码的作者的详细信息。