39、Python 相关规范与政策解读

Python 相关规范与政策解读

1. 文档字符串规范（PEP 257）

文档字符串（docstring）在 Python 中是一种重要的注释方式，用于描述函数、类、模块等的功能和使用方法。

1.1 单行文档字符串

单行文档字符串用于简单描述函数的功能，例如：

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

这里的 “Do X” 应替换为具体的功能描述。

1.2 多行文档字符串

多行文档字符串由摘要行、空行和详细描述组成。摘要行可被自动索引工具使用，应单独一行，并与文档字符串的其余部分用空行分隔。摘要行可以与开头引号在同一行，也可以在下一行。整个文档字符串的缩进与第一行引号的缩进相同。
示例如下：

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
    ...

1.3 不同对象的文档字符串要求