如何记录 python 包答案

【问题标题】：how to document a python package如何记录 python 包
【发布时间】：2014-07-03 23:11:32
【问题描述】：

我知道记录函数、类和模块的标准方法是什么，但是我如何记录包 - 我是在 __init__.py 中放置一个文档字符串，还是在其他地方？

【问题讨论】：

【解决方案1】：

是的，就像函数或类注释一样，__init__.py 文件中的第一项应该是注释字符串：

"""
This is the xyz package.
"""

现在，如果您导入包并使用 help(package)，您将看到您的文档字符串。在此处查看更多信息：http://www.python.org/dev/peps/pep-0257/

【讨论】：

【解决方案2】：

见PEP257

一个包可能记录在包目录中的 __init __.py 文件的模块文档字符串中。

【讨论】：

【解决方案3】：

记录是个好主意，只要您不在代码中记录明显的内容

尝试理解大多数阅读您的源代码的人都会理解 python，所以像这样评论或记录行是没有意义的：

a = 1     #this assigns 1 to a

但是评论或记录一个相当复杂的函数或类是个好主意。

一般经验法则：想象下一个处理您的代码的人是一个挥舞斧头的疯子，他们知道您住在哪里。

这样你总是会留下“有用”的 cmets/doc 的

【讨论】：