python - 如何正确记录类的静态变量？

Question

在类中记录静态变量的首选方法是什么？

class Foo(object):
    """
    Foo doc.
    """

    bar = 'bar'
    """
    Bar doc.
    """


class Foo(object):
    """
    Foo doc.
    """

    # Bar doc.
    bar = 'bar'

还有什么……？

Answer 1

没有办法将文档字符串与变量相关联。添加属性文档字符串的PEP失败。

代码文档的最佳方式可能是注释而不是文档字符串，这样您就不会引入 PEP 讨论的那种歧义。如果您希望它们包含在help()文档中，您还可以在类的文档字符串中记录它们。

Answer 2

Epydoc文档工具确实提供了对可变文档字符串的支持：

http://epydoc.sourceforge.net/manual-docstring.html#variable-docstrings

格式就像您在上面建议的那样：

如果变量赋值语句后面紧跟一个裸字符串文字，则该赋值被视为该变量的文档字符串

Answer 3

我个人使用 Google 风格的 DocString 格式，我处理静态属性的方法是将它们包含在类的 DocString 中。

例如

class Bicycle:
    """
    A class defining a Bicycle

    Attributes:
        NUM_WHEELS (int): The number of wheels that a bicycle has: 2.
    """
    NUM_WHEELS = 2

不过，这绝对是一个自以为是的话题。根据您希望属性的可见程度，使用属性定义上方的普通注释来记录它们也可能是有意义的。例如

class Bicycle:
    """
    A class defining a Bicycle
    """
    # The number of wheels that a bicycle has
    NUM_WHEELS = 2