Python模块的注释有规范吗？

Question

据我所知，模块文档字符串应该只提供模块的一般描述，作者和版本等详细信息应该只包含在模块的注释中。

然而，我已经看到了以下的注释和文档字符串:

__author__ = "..."
__version__ = "..."
__date__ = "..."

这些项目的正确位置在哪里？在模块顶部列出哪些其他常见的__[name]__变量？

- Jace Browning

Answer 1

它们仅仅是惯例，尽管是非常广泛使用的惯例。请参阅Python元数据要求集的描述。

__version__在Python样式指南中提到。

关于文档字符串，有一个PEP专门为您而设！

模块的文档字符串通常应列出由模块导出的类、异常和函数（以及任何其他对象），并对每个对象进行一行摘要说明。（这些摘要通常比对象的文档字符串中的摘要线条提供更少的细节。）一个软件包的文档字符串（即软件包的init.py模块的文档字符串）还应列出软件包导出的模块和子软件包。

- Katriel

Answer 2

您可以查看以下内容：

• Epydoc，特别是其预定义的字段。
• Pydoc

- Bruno

Answer 3

我建议不要担心__author__，__version__等属性。这些属性由任何体面的版本控制系统处理。只有在需要在生产系统上拥有该信息的情况下才添加它们，此时源代码已经从版本控制系统中导出。

- Gintautas Miliauskas

---

但是PEP 8规定，如果您必须在源文件中使用Subversion、CVS或RCS的辅助信息，请按照以下方式进行操作。version = "$Revision: 84354 $"

$Source$

这些行应该包含在模块的文档字符串之后，在任何其他代码之前，上下方都应该有一个空行分隔。 - Maxim Popravko