Question

我没有找到关于应该在类和__init__文档字符串中记录的内容的最佳实践。有时我发现构造函数参数已经记录在docstring类中，有时会在__init__ docstring中描述。我更喜欢在类docstring中描述构造，因为这是您在创建新实例时调用的内容。但是应该在__init__方法文档字符串中记录什么呢？

编辑：

我知道google styleguide和google docstring style example，但两者都没有回答我的问题。 docstring样式示例确实说

__init__方法可以在类级别中记录 docstring，或__init__方法本身的文档字符串。任何一种形式都是可以接受的，但这两种形式不应混合。选一个约定记录__init__方法并与之保持一致。

但是如果我选择将__init__函数的docstring放到类级docstring中，那么__init__ docstring应该包含什么？

Answer 1

该类的实际用法是由SampleClass(args)之类的命令初始化的，并且没有用户要输入SampleClass.__init__(args)，因此从最终用户的角度来看，当他们感到困惑时，他们更有可能打字

help(SampleClass)

代替

help(SampleClass.__init__)

因此，我认为将所有文档放入SampleClass的文档字符串中是有意义的。
并且在__init__的文档字符串中放入“请参阅help(SampleClass)以获取更多信息” ，以防万一有人（或某些程序）正在看它。 >

Answer 2

我个人尝试尽可能使用google styleguide

使用__init__创建新实例时，应记录哪些成员变量已初始化。然后其他人知道他们需要在以后的代码中访问它们时可以期待什么。

Google样式指南中的示例：

class SampleClass(object):
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam=False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

Answer 3

我不知道在这一点上有任何共识。

但是，sphinx autodoc模块允许从 docstring 生成文档。因此，它往往会强制执行一致的 docstring 文档。

在您的情况下，我会在class docstring 中记录class 和构造函数参数的内容，如：

class MyClass:
    """I am a class.
    I do funny stuff

    :type tags: dict
    :param tags: A dictionary of key-value pairs
    """

    def __init__(tags):
        self.tags = tags

Answer 4

在PEP 257（文档字符串PEP）中有一个官方的答案，可以说是权威的：

类构造函数的__init__方法应记录在文档字符串中。

这是很合逻辑的，因为这是函数和方法的通常过程，__init__()也不例外。

因此，这会将代码及其文档放在同一位置，从而有助于维护。

最后，向用户显示文档的工具（如Jupyter或内置的Python Shell命令help()）更有可能正确显示代码的文档。实际上，当您在 class 上寻求帮助时，他们会 do 自动显示__init__()文档字符串，因此这是遵循官方惯例的另一个原因__init__()中的初始化文档。

Answer 5

类文档应包含对象的 public 组件。 __init__参数可能是公共的，也可能不是公共的，因此它们是否包含在类文档字符串中取决于对象的设计。

PEP 257中的完整段落指出：

类的文档字符串应总结其行为并列出公共方法和实例变量。如果该课程旨在子类化，并具有子类的附加接口，接口应单独列出（在文档字符串中）。班级构造函数的__init__应该记录在文档字符串中方法。个别方法应由自己记录文档字符串。

然后google style guide声明：

在类定义下面，类应具有文档字符串班级。如果您的班级具有公共属性，则应该此处记录在“属性”部分，并遵循相同的内容格式化为函数的Args部分。

因此，文档确定取决于__init__的参数是否为 public 。如果对象的目的是让用户构造自己的实例，则__init__参数应记录在类docstring中。但是，如果在内部构造对象然后返回给用户，则类文档应仅引用对象的公共方面。

因此，以下来自google的示例建议来自likes_spam的{{1}}参数是公开的：

__init__

但是，在class SampleClass(object): """Summary of class here. Longer class information.... Longer class information.... Attributes: likes_spam: A boolean indicating if we like SPAM or not. eggs: An integer count of the eggs we have laid. """ def __init__(self, likes_spam=False): """Inits SampleClass with blah.""" self.likes_spam = likes_spam self.eggs = 0 def public_method(self): """Performs operation blah."""期间，基于两个内部参数likes_spam和__init__确定了公共spam_count下面的属性。因此，like_threshold记录在类docstring中，而likes_spam和spam_count记录在like_threshold docstring中。

__init__

Answer 6

Numpy说您应该在类文档中记录__init__。 https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard

这是一个示例，您可以看到__init__没有文档字符串的情况。相反，它显示在类文档中。 https://github.com/numpy/numpy/blob/master/numpy/core/records.py

Answer 7

Google有自己的Python风格指南，这并不是一件坏事。以下是他们认为文档字符串最佳做法的链接：http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

是否应该在类和init docstrings中记录哪些内容？

7 个答案:

是否应该在类和__init__ docstrings中记录哪些内容？

7 个答案:

是否应该在类和init docstrings中记录哪些内容？