在 python 模块文档字符串中放入啥？ [关闭]

Posted 2023-02-19

【中文标题】在 python 模块文档字符串中放入啥？ [关闭]

【英文标题】：What to put in a python module docstring? [closed]在 python 模块文档字符串中放入什么？ [关闭]

【发布时间】：2011-02-03 04:01:09

【问题描述】：

好的，我已经阅读了PEP 8 和PEP 257，并且我已经为函数和类编写了很多文档字符串，但是我有点不确定模块文档字符串中应该包含什么内容。我想，至少，它应该记录模块导出的函数和类，但我也看到了一些列出作者姓名、版权信息等的模块。有没有人有一个好的 python 文档字符串应该如何的例子结构化？

【参考方案1】：

想想有人在交互式解释器的提示下做help(yourmodule)——他们想知道什么？ （其他提取和显示信息的方法在信息量上大致相当于help）。所以如果你在x.py:

"""This module does blah blah."""

class Blah(object):
  """This class does blah blah."""

然后：

>>> import x; help(x)

显示：

Help on module x:

NAME
    x - This module does blah blah.

FILE
    /tmp/x.py

CLASSES
    __builtin__.object
        Blah

    class Blah(__builtin__.object)
     |  This class does blah blah.
     |  
     |  Data and other attributes defined here:
     |  
     |  __dict__ = <dictproxy object>
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__ = <attribute '__weakref__' of 'Blah' objects>
     |      list of weak references to the object (if defined)

如您所见，这些组件的文档字符串中已经包含了关于类（以及函数，虽然我没有在这里展示）的详细信息；模块自己的文档字符串应该非常概括地描述它们（如果有的话），而是专注于模块作为一个整体可以为您做什么的简明总结，最好是一些经过文档测试的示例（就像理想情况下函数和类应该在他们的文档字符串）。

我看不出诸如作者姓名和版权/许可之类的元数据如何帮助模块的用户——它可以进入 cmets，因为它可以帮助考虑是否重用或修改模块的人。

【讨论】：

那么，习惯上在模块顶部的 cmets 中包含作者、版权等？

@007brendan，这是很常见的做法，是的。

@IfLoop 我怀疑在解释器中使用help() 方法的用户比仅仅阅读代码的用户更多。

请记住，要记录的最重要的事情是为什么。记录某事的作用是编写良好代码的工作。记录为什么是文档的工作。

@ErikAronesty 我不确定我是否完全理解“记录原因”的含义。您是否有任何文档解释此类做法的概念和示例？

【参考方案2】：

引用specifications：

脚本的文档字符串 （一个独立的程序）应该可以用作它的“使用”消息，当使用不正确或缺少参数（或者可能带有“-h”选项，用于“帮助”）调用脚本时打印。这样的文档字符串应该记录脚本的函数和命令行语法、环境变量和文件。使用消息可以相当详细（几个屏幕已满），应该足以让新用户正确使用该命令，以及为老练用户提供对所有选项和参数的完整快速参考。

模块的文档字符串 通常应该列出模块导出的类、异常和函数（以及任何其他对象），并用一行总结。 （这些摘要通常比对象文档字符串中的摘要行提供的详细信息更少。）包的文档字符串（即包的__init__.py 模块的文档字符串）还应该列出包导出的模块和子包。

类的文档字符串 应该总结其行为并列出公共方法和实例变量。如果该类打算被子类化，并且具有子类的附加接口，则应单独列出该接口（在文档字符串中）。类构造函数应记录在其__init__ 方法的文档字符串中。各个方法应由它们自己的文档字符串记录。

函数或方法的文档字符串 是以句号结尾的短语。它将功能或方法的效果规定为命令（“执行此操作”、“返回该操作”），而不是描述；例如不要写“返回路径名......”。函数或方法的多行文档字符串应总结其行为并记录其参数、返回值、副作用、引发的异常以及何时可以调用它的限制（如果适用）。应指明可选参数。应该记录关键字参数是否是接口的一部分。