Question

一方面，我们鼓励我们创建字段，而不是使用其他语言建模的额外存取函数来包含我们的python类。

另一方面，PEP for 'attribute docstrings'被拒绝了。

第三方面，epydoc和sphinx支持他们。冒着非建设性问题的风险，在类中记录变量是否存在单一，明确，通用的做法？

Answer 1

自从我被要求这样做以后，我将我的评论改为答案。

通常，实例（公共）属性是不言自明的，用户使用它们不需要文档。属性的名称和上下文足以说明属性是什么，您可以在类的文档中添加一些有关如何处理它的文档。

您可能最终会在某些情况下向用户提供属性的访问权限，但该属性不够自我解释和/或其处理需要注意（因为如果处理不当，可能会“吹”事情“）。

例如，您可能希望让用户知道属性应具有特定的“接口”以允许其使用。或者您必须解释属性必须满足的条件。

在这种情况下，将文档与课程文档放在一起并不是一个好主意，因为课程的文档越来越长，它解释了很多非常具体的知识。

简单而且我认为更优雅的解决方案是使用属性。属性允许您向属性添加文档字符串，为您提供一种实际控制对其的访问的方法，从而允许使类更健壮。

如果你必须处理很多属性，那么编写数十个属性可能很麻烦，但你仍然可以动态添加它们，例如使用装饰器。这非常有效，特别是如果你只是想添加一个docstring，总是使用相同类型的getter / setter。

例如你可以写：

def set_properties(names_to_docs):
    def decorator(cls):
        for name, doc in names_to_docs.items():
            prop = property((lambda self: getattr(self, '_{}'.format(name))),
                            (lambda self, val: setattr(self, '_{}'.format(name), val),
                            doc=doc)
            setattr(cls, name, prop)
        return cls
    return decorator

并像这样使用它：

>>> @set_properties({'a': 'This is a', 'b': 'This is b'})
>>> class Test:
...     def __init__(self):
...         self._a = 1
...         self._b = 2
... 
>>> print(Test.a.__doc__)
This is a
>>> Test().a
1

在评论中，Lukas Graf指出您可以使用Zope.interface创建一个简单描述具体类的类，这使您有机会将文档字符串添加到属性中。这可能是另一种选择。我没有使用Zope.interface的经验，所以我无法准确地说出你能做什么，怎么做，以及最终如何与自动文档程序进行交互。

是否常用python属性docstrings？

1 个答案: