在 Python 类中为 __init__ 方法编写文档字符串的首选位置在哪里？答案

【问题标题】：Where is the preferred location to write the the docstring for the __init__ method in a Python class?在 Python 类中为 __init__ 方法编写文档字符串的首选位置在哪里？
【发布时间】：2015-02-13 06:00:08
【问题描述】：

我有一个关于文档字符串标准的问题。链接：http://sphinxcontrib-napoleon.readthedocs.org/en/latest/example_google.html 非常有用，但它说在 Python 类中为 init 方法编写文档字符串可以在类头或 init 下完成标题。我想知道人们对此有何想法，即以一种或另一种方式做这件事的利弊。

【问题讨论】：

我认为这主要是基于意见的问题。把它放在对你最有帮助的地方。我，如果 __init__ 没有做任何特别的事情，会将它放在类文档中，因为你可以使用 print ClassName.__doc__ 轻松查看它的其他详细信息。
What is the standard Python docstring format?的可能重复
你一般调用__init__方法调用类，所以建议放在这里。您想记录如何创建类实例。还有__new__ 方法。将文档字符串放在方法而不是类下意味着用户必须知道调用了哪个方法才能通过Class.__init__.__doc__ 找到其文档字符串。因此，您使查找该信息变得更加困难。请注意，内置函数将这些信息放在类中，可能是出于这个原因。顺便说一句：如果你愿意，你可以同时记录这两者……

标签： python class coding-style init docstring

【解决方案1】：

any 方法的文档字符串应直接出现在方法定义的下方。所以我认为 init 方法的文档字符串也应该出现在它的定义之下。

【讨论】：

【解决方案2】：

这完全是见仁见智。一种方法相对于另一种方法没有优点或缺点。在我看来，init 的文档字符串应该放在 init 方法下，因为最好将 init 文档字符串与类文档字符串分开。

【讨论】：