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

Question

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

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

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

Answer 1

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

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

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