python 文档字符串 docstrings 用法规范

文档字符串用来描述函数、类和方法。它是一个重要的工具，不仅使程序更加简洁易懂，而且还方便程序的编写。一对引号之间的内容是字符串，三对引号之间的内容是文档字符串。下面是一个简单的例子：

def add(x, y):
    """
    引号里的内容是文档字符串.
    这个函数接受两个参数，将它们相加并返回
    """
    result = x + y
    return result

我们可以通过 function_name.__doc__ 的方式查看函数的文档字符串：

>>> add.__doc__
引号里的内容是文档字符串.
这个函数接受两个参数，将它们相加并返回

类似于python有它的编写规范，docstrings也有它的编写规范。不遵守规范虽然不会影响代码的运行，但是不利于别人阅读你的代码。我们可以查看几个python内置函数的docstrings：

>>> print(max.__doc__)
max(iterable, *[, default=obj, key=func]) -> value
max(arg1, arg2, *args, *[, key=func]) -> value

With a single iterable argument, return its biggest item. The
default keyword-only argument specifies an object to return if
the provided iterable is empty.
With two or more arguments, return the largest argument.

>>> print(print.__doc__)
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)

Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file:  a file-like object (stream); defaults to the current sys.stdout.
sep:   string inserted between values, default a space.
end:   string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.

可以看出，规范的文档字符串分两个部分，中间用一个空行隔开。第一部分描述函数的参数（注意位置参数和关键字参数的表示方式）、是否返回值（有无 -> value）；第二部分说明函数的用法，如果参数有很多，还需要说明各参数的含义。

回到开始时的例子，规范的文档字符串如下：

def add(x, y):
    """
    add(x, y) -> value

    返回两个参数的和
    """
    result = x + y
    return result

使用规范的文档字符串的另一个好处：在有自动补全的IDE中，输入函数名和括号，该函数的所有参数都将出现在括号中。在调用函数的时候，就不用跑到函数定义的地方去看参数的位置和关键字，可以省时间。

把文档字符串打印出来，会看到很有意思的事：

>>> """one
... two
... three"""
'one\ntwo\nthree'

python 文档字符串 docstrings 用法规范

猜你喜欢