Docstring——将文档写在代码中

文档字符串(docstring)是书写在源代码中的文档,类似于注释。但它和注释及javadoc不一样,会在运行时中保留,这样在程序运行时也可以查看文档信息。

Python,Lisp和Julia等语言都支持这一功能。

在Python的交互式界面下,我们可以通过help()函数显示docstring。

>>> import requests
>>> help(requests.get)
Help on function get in module requests.api:
get(url, params=None, **kwargs)
    Sends a GET request.
    :param url: URL for the new :class:`Request` object.
    :param params: (optional) Dictionary or bytes to be sent in the query string for the :class:`Request`.
    :param \*\*kwargs: Optional arguments that ``request`` takes.
    :return: :class:`Response <Response>` object
    :rtype: requests.Response

Python中,docstring用三个引号引起来。位于文件开头则是对整个文件的说明。位于类或者函数下方则是对这两者的说明。

例如上面的代码显示的requests的get函数的说明在源代码中是这样保存的:

def get(url, params=None, **kwargs):
    r"""Sends a GET request.
    :param url: URL for the new :class:`Request` object.
    :param params: (optional) Dictionary or bytes to be sent in the query string for the :class:`Request`.
    :param \*\*kwargs: Optional arguments that ``request`` takes.
    :return: :class:`Response <Response>` object
    :rtype: requests.Response
    """
    kwargs.setdefault('allow_redirects', True)
    return request('get', url, params=params, **kwargs)

我们可以分析一下docstring都由哪几部分组成。比如一个函数,一般由简介、参数、返回值和返回类型构成docstring的内容。

根据Python的PEP 257标准,python文件一般都要求有docstring。Docstring作为注释,可以使代码更容易被别人读懂。同时它也能方便的在Python终端中被调用。