Python的docstring规范（说明文档的规范写法）

其实，标准规范里，python代码写完都要进行规范性测试。

比如：

black .  # 帮你添加空格，看起来好看
flake8  # 检查不规范的地方

然后会检查出代码不规范的地方，进而修改，比如下面这样的

所以要了解这个东西的规范，

• 一种就是去python官网，看相应的PEP文件，源网页点击这里
• 另一种就是去谷歌的python规范里找docstring相关内容，源网页点击这里
• 中文很直观，不过不是很全，参考菜鸟教程：Python 文档字符串(DocStrings)

1. python dostring规范（PEP）

来源：https://www.python.org/dev/peps/pep-0257/

有好人翻译了重点的一部分，感谢：PEP 257 文档字符串规范总结

不过我还是都看看好了

---

1.1 docstring的作用

一. docstring是一种出现在模块、函数、类或者方法定义的第一行说明的字符串，这种docstring就会作为该对象的__docs__属性。

---

二. 从规范角度来说，所有的模块都应该有docstrings，那些从模块中引入的函数和类也要有docstrings。公有方法（包括__init__构造器）也要有docstring。对于一个包来说，包的说明文档可能就来自__init__文件中的docstring.

例如：

import collections
help(collections)

可以在collections->__init__.py中找到help函数返回的内容

这是对应的文件

---

三. Python代码中其他地方出现的字符串也可以作为文档，但是其不会被Python字节编码器识别，也就无法作为运行时对象属性（也就无法被分配给__doc__方法），但是有两种额外类型的docstrings可以被软件工具提取。

1. 在模块、类或者__init__方法最开始地方简单的赋值语句之后的字符串，被称为“属性说明文档” (attribute docstrings)
2. 紧跟着另一个docstrings出现的字符串称为“附加文档”（dditional docstrings）

• 参考PEP 258，查看关于属性文档和附加文档的详细说明
• 为了保证一致性，
  • 在文档字符串周围使用 """your docstring"""。
  • 如果在文档字符串中使用任何反斜杠转义，那么需要用 r"""your raw docstring"""。
  • 对于 Unicode 文档字符串，请使用 u"""your Unicode docstring """。

1.2 docstring的表现形式

python的docstring有两种，一种是单行，一种是多行（就是字面意思，有的注释文档是写在一行，有的需要回车，写成多行）

单行docstring

单行docstring适用于极少数情况，你的说明文档恰好可以写在一行里面，这时候可以使用单行docstring。

def kos_root():
    """Return the pathname of the KOS root directory."""
    global _kos_root
    if _kos_root: return _kos_root
    ...

注意：

1. 即使字符串适合一行，也使用三引号，这样以后扩展起来比较容易
2. 结束引号与开始引号在同一行，这样单行看起来好看
3. 在文档字符串之前或之后都没有空行。
4. 文档字符串是以句号结尾的短语，描述的内容应该是"Do this", "Return that"，这个函数是用来干嘛的，函数参数如何，函数返回什么，不应该写其他无关内容。
5. 单行文档字符串的内容，不应该是函数/方法的重复说明，比如下面这种就不值得提倡

   def function(a, b):
       """function(a, b) -> list"""
   

   赖好应该是这样的：

   def function(a, b):
   """Do X and return a list."""
   

---

多行docstring

• 多行docstrings由一个总结/总结行（类似单行说明文档）、一个空行，然后是其他更详细的内容描述。
  • 摘要行可以被自动索引工具使用，因此它需要符合位于第一行且后面空一行以和其他部分隔开这样的规范。
  • 总结行可以和开始的引号在一行，也可以在下一行。
  • 整个文档的缩进和第一行一样，如下面的例子。
• 一个类的所有docstrings后面，要插入一个空行。（和后面的代码隔开）
  • 一般类方法会用一个空行和其他内容分开，docstrings和第一个方法之间要有个空格
• 脚本（一个独立程序，比如一个.py文件）的docstring应该可以作为它的usage信息，比如脚本被不正确的调用，或者还使用-h参数时，就会打印出这个信息。
  • 这样的docstring应该记录了脚本的函数功能，还有命令行语法，环境变量以及文件等等。用法消息可能会很多，甚至好几个屏幕，但是起码要写的能让新用户可以正确使用这个脚本，同时对于熟练用户来说也是一个所有功能列表的快速参考。
• 不要使用 Emacs 约定在运行文本中以大写形式提及函数或方法的参数。 Python 区分大小写，参数名称可用于关键字参数，因此文档字符串应记录正确的参数名称。最好在单独的行中列出每个参数。

示例1：

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

示例2：

class Variable:
    """
    Attributes:
    history (:class:`History` or None) : the Function calls that created this variable or None if constant
    derivative (variable type): the derivative with respect to this variable
    grad (variable type) : alias for derivative, used for tensors
    name (string) : a globally unique name of the variable
    """

    def __init__(self, history, name=None):
        global variable_count
        assert history is None or isinstance(history, History), history

        self.history = history
        self._derivative = None

        # This is a bit simplistic, but make things easier.
        variable_count += 1
        self.unique_id = "Variable" + str(variable_count)

        # For debugging can have a name.
        if name is not None:
            self.name = name
        else:
            self.name = self.unique_id
        self.used = 0

    def requires_grad_(self, val):
        """
        Set the requires_grad flag to `val` on variable.

        Ensures that operations on this variable will trigger
        backpropagation.

        Args:
            val (bool): whether to require grad
        """
        self.history = History()

2. Google Styleguide

来源：https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings

直接看模板就好了

2.1 模块docstrings

如果是一个模块，那么文件的最开始，应该有类似以下内容：

"""A one line summary of the module or program, terminated by a period.

Leave one blank line.  The rest of this docstring should contain an
overall description of the module or program.  Optionally, it may also
contain a brief description of exported classes and functions and/or usage
examples.

  Typical usage example:

  foo = ClassFoo()
  bar = foo.FunctionBar()
"""

---

2.2 函数和方法

• 文档字符串应该提供足够的信息来编写对函数的调用，而无需阅读函数的代码。文档字符串应描述函数的调用语法及其语义，但通常不描述其实现细节，除非这些细节与函数的使用方式相关
• 函数的描述信息中有几个部分是比较特殊，需要进行特殊指明的。比如：
  • 参数，按名称列出每个参数，名称后面就跟着描述，用冒号/空格/换行符分开名称和描述。如果描述信息太长，单行超过80个字符，可以使用比参数名称多2或4个空格的悬空缩进（与文件中其余的docstring保持一致）。如果代码不包含相应的类型注释，则说明应包括所需的类型。如果函数接受foo（变长参数列表）和/或**bar（任意关键字参数），则它们应列为foo和**bar。
  • 类似的还有return和raise，这两种特殊类型的说明

如果是函数和方法，那么其docstring应该类似下面：

def fetch_smalltable_rows(table_handle: smalltable.Table,
                          keys: Sequence[Union[bytes, str]],
                          require_all_keys: bool = False,
) -> Mapping[bytes, Tuple[str]]:
    """Fetches rows from a Smalltable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by table_handle.  String keys will be UTF-8 encoded.

    Args:
        table_handle: An open smalltable.Table instance.
        keys: A sequence of strings representing the key of each table
          row to fetch.  String keys will be UTF-8 encoded.
        require_all_keys: If True only rows with values set for all keys will be
          returned.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {b'Serak': ('Rigel VII', 'Preparer'),
         b'Zim': ('Irk', 'Invader'),
         b'Lrrr': ('Omicron Persei 8', 'Emperor')}

        Returned keys are always bytes.  If a key from the keys argument is
        missing from the dictionary, then that row was not found in the
        table (and require_all_keys must have been False).

    Raises:
        IOError: An error occurred accessing the smalltable.
    """

2.3 类

class SampleClass:
    """Summary of class here.

    Longer class information....
    Longer class information....

    Attributes:
        likes_spam: A boolean indicating if we like SPAM or not.
        eggs: An integer count of the eggs we have laid.
    """

    def __init__(self, likes_spam: bool = False):
        """Inits SampleClass with blah."""
        self.likes_spam = likes_spam
        self.eggs = 0

    def public_method(self):
        """Performs operation blah."""

3. 其他

minitorch/slides-master/docs/slides+build2/module0.1.html#/14