Python 中惯用的文件级注释？

Question

当我需要编写有关函数的大量注释时，我使用文档字符串。但是，我不确定 Python 中文件级注释的等效项是什么，以及它对于模块与脚本是否有所不同。

这种风格常用吗？

"""
file.py: module for X
Detailed information...
"""

import x

def foo(bar):
  return 42

或者也许是这个？

# file.py: module for X
# More info...

import x
# ...

有什么想法吗？

Answer 1

始终使用字符串，因为它实际上会填充__doc__当前文件/模块的变量。

比较一下：

'''Hello World'''
print(__doc__)

到

# Hello World
print(__doc__)

考虑这是在一个模块中foo.py并比较输出：

>>> import foo
>>> help(foo)

您也不需要添加“file: ...”部分，因为 python 会自动显示该部分。