Python模块注释有规范吗？

Question

我理解模块的文档字符串（docstring）应该只是简单描述一下这个模块的功能，而像作者和版本这样的细节信息应该放在模块的注释里。

不过，我在注释和文档字符串里都见过以下内容：

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

那么，像这些信息放在哪里才是正确的呢？还有哪些 __[name]__ 变量通常会在模块的开头列出呢？

Answer 1

我建议你不用太担心 __author__、__version__ 这些东西。这些信息其实是由任何一个不错的版本控制系统来管理的。只有在你需要在生产环境中显示这些信息，也就是当源代码已经从版本控制系统导出后，才需要添加它们。

Answer 2

你可以看看：

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

Answer 3

这些只是一些约定，虽然它们被广泛使用。你可以看看这个描述，里面讲了一些Python的元数据要求。

__version__在Python风格指南中提到过。

关于文档字符串，还有专门为你准备的PEP！

一个模块的文档字符串通常应该列出这个模块导出的类、异常和函数（以及其他对象），并给出每个的简短总结。（这些总结通常比对象文档字符串中的总结要简略。）一个包的文档字符串（也就是包的init.py模块的文档字符串）也应该列出包导出的模块和子包。