Python 在类和_init__docstrings中应该记录什么内容，是否有共识？
我没有找到任何关于类和Python 在类和_init__docstrings中应该记录什么内容，是否有共识？,python,docstring,code-documentation,Python,Docstring,Code Documentation,我没有找到任何关于类和\uuuu init\uuudocstrings中应该记录什么的最佳实践。有时我发现构造函数参数已经记录在类docstring中，有时构造函数参数在\uuuu init\uuudocstring中描述。我更喜欢在类docstring中描述构造，因为这是创建新实例时所调用的。但是\uuuu init\uuu方法docstring中应该记录什么呢 编辑： 我知道和，但都没有回答我的问题。docstring样式的示例确实说明 \uuuu init\uuuu方法可以在类级别或 d
\uuuu init\uuu\uuuu init\uuu\uuuu init\uuu编辑： 我知道和，但都没有回答我的问题。docstring样式的示例确实说明
\uuuu init\uuuu\uuu init\uu\uuuu init\uuuu但是，如果我选择将
\uuuuu init\uuuu\uuuuuu init\uuu\uuuu init\uuuu类示例类（对象）：
“这里是课堂总结。
更长的班级信息。。。。
更长的班级信息。。。。
属性：
喜欢垃圾邮件：一个布尔值，指示我们是否喜欢垃圾邮件。
蛋：我们产下的蛋的整数计数。
"""
def uuu init uuu（self，likes_spam=False）：
“”“用blah初始化SampleClass。”“”
self.likes\u spam=likes\u spam
self.eggs=0
def公共_方法（自身）：
“”“执行操作废话。”“”
类类类的实际使用是由类似于
SampleClass（args）SampleClass
从最终用户的角度来看，当他们感到困惑时，他们更有可能键入
help(SampleClass)
而不是
help(SampleClass.__init__)
因此，我认为将所有文档放入SampleClass
的docstring中是有意义的。
在\uuuu init\uuuuu
的docstring中放上“请参阅帮助（SampleClass）
了解更多信息”，以防有人（或某个程序）看到它。Numpy说你应该在类文档中记录\uu init\uuuu
下面是一个示例，您可以看到\uuuu init\uuu
没有docstring。相反，它显示在类文档中。
在（docstring PEP）中有一个官方答案，可以说是权威的：
类构造函数应该记录在docstring中，用于它的\uuuu init\uuu
方法
这是非常合乎逻辑的，因为这是函数和方法的常规过程，\uuuu init\uuuu（）
也不例外
因此，这会将代码及其文档放在同一位置，这有助于维护
最后，向用户显示文档的工具（如Jupyter或内置的pythonshell命令help（）
）更有可能正确显示代码的文档。实际上，当您请求类的帮助时，它们会自动显示\uuuuu init\uuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuu（）
文档字符串，因此这是遵循将初始化文档放入中的官方惯例。\uuuu init\uuuu
参数可能是公共的，也可能不是公共的，因此它们是否包含在类docstring中取决于对象设计
全文如下：
类的docstring应该总结其行为并列出
公共方法和实例变量。如果该类的目的是
子类，并为子类提供了一个附加接口
接口应单独列出（在docstring中）。班级
构造函数的\uuuu init\uuuuu
方法。个别方法应自行记录
文件串
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, spam_count, like_threshold=1):
"""Inits SampleClass.
Args:
spam_count: The amount of SPAM consumed.
like_threshold: The threshold consumed that indicates
whether we like SPAM.
"""
self.likes_spam = spam_count > like_threshold
self.eggs = 0
def public_method(self):
"""Performs operation blah."""
各国：
类在类定义下面应该有一个docstring来描述
这个班。如果您的类具有公共属性，则它们应该是
在此处的“属性”部分中记录，并遵循相同的步骤
格式化为函数的Args节
因此，文档的确定取决于\uuuu init\uuu
的参数是否为公共。如果对象的目的是让用户构造自己的实例，则应在类docstring中记录\uuuu init\uuuu
参数。但是，如果对象是在内部构造的，然后返回给用户，那么类文档应该只引用对象的公共方面
因此，以下来自google的示例表明\uuuu init\uuuu
中的likes\u spam
参数是公共的：
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."""
但是，下面的publiclikes\u spam
属性是在初始化期间基于两个内部参数spam\u count
确定的
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, spam_count, like_threshold=1):
"""Inits SampleClass.
Args:
spam_count: The amount of SPAM consumed.
like_threshold: The threshold consumed that indicates
whether we like SPAM.
"""
self.likes_spam = spam_count > like_threshold
self.eggs = 0
def public_method(self):
"""Performs operation blah."""