是否有Python模块注释的约定？

Question

我的理解是，模块文档字符串应该只提供模块所做的一般描述，而作者和版本等细节只应包含在模块的注释中。

但是，我在评论和文档字符串中看到了以下内容：

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

放置这些物品的正确位置在哪里？ 还有哪些其他__[name]__变量在模块顶部列出？

Answer 1

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

Python样式指南中提到了__version__ 。

关于docstrings，有一个PEP只为你 ！

模块的docstring通常应列出模块导出的类，异常和函数（以及任何其他对象），每个对应的摘要。 （这些摘要通常提供的细节少于对象文档字符串中的摘要行。）包的docstring（即包的init .py模块的docstring）也应列出包导出的模块和子包。

Answer 2

你可以看看：

• Epydoc ，更具体地说是它的预定义字段 。
• 是pydoc

Answer 3

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