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

Question

在类里面，怎么记录静态变量是比较好的方式呢？

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

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


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

    # Bar doc.
    bar = 'bar'

还有其他的方法吗...?

Answer 1

Epydoc 是一个文档工具，它支持为变量添加说明文字：

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

这种说明的写法就像你上面提到的那样：

如果一个变量赋值语句后面紧跟着一个简单的字符串，那么这个赋值就会被当作该变量的说明文字。

Answer 2

我个人使用的是谷歌风格的文档字符串格式，对于静态属性，我的做法是把它们放在类的文档字符串里。

比如：

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

Answer 3

没有办法把文档字符串和变量关联起来。之前有个提案想要添加这个功能，但没有成功。

对于代码的说明，最好的方法可能是使用注释，而不是文档字符串，这样可以避免一些提案中提到的模糊情况。如果你想在 help() 和文档中看到这些信息，也可以在类的文档字符串里进行说明。