文档字符串约定在PEP-257中比PEP-8详细得多。

然而，文档字符串似乎比其他代码区域更加个性化。不同的项目会有自己的标准。

我总是倾向于包含文档字符串，因为它们倾向于快速演示如何使用函数以及它的功能。

我更喜欢保持一致，不管字符串的长度。我喜欢如何编码时，缩进和间距是一致的。这意味着，我使用:

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

结束:

def sq(n):
    """Returns the square of n."""
    return n * n

并且倾向于在较长的文档字符串中省略第一行注释:

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

这意味着我发现像这样开始的文档字符串是混乱的。

def sq(n):
    """Return the squared result. 
    ...

谷歌风格指南包含一个优秀的Python风格指南。它包含了可读文档字符串语法的约定，提供了比PEP-257更好的指导。例如:

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

我喜欢将此扩展为在参数中包含类型信息，如本Sphinx文档教程所述。例如:

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

这是Python;任何事情都可能发生。考虑如何发布您的文档。除了源代码的读者，文档字符串是不可见的。

人们真的很喜欢在网上浏览和搜索文档。要实现这一点，请使用文档工具Sphinx。它是记录Python项目的事实上的标准。产品很漂亮-看看https://python-guide.readthedocs.org/en/latest/。“阅读文档”网站将免费保存你的文档。

显然没有人提到它:你也可以使用Numpy文档字符串标准。它被广泛应用于科学界。

numpy格式的规范以及一个示例 您有一个sphinx扩展来渲染它:numpydoc 一个漂亮的文档字符串的示例:http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

用于解析google风格文档字符串的Napolean sphinx扩展(在@Nathan的回答中推荐)也支持numpy风格的文档字符串，并对两者进行了简短的比较。

最后是一个基本的例子来说明它是怎样的:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True

格式

Python文档字符串可以按照其他文章所示的几种格式编写。但是没有提到默认的Sphinx文档字符串格式，它基于reStructuredText (reST)。你可以在这篇博文中获得一些关于主要格式的信息。

注意，reST是PEP 287推荐的

以下是文档字符串使用的主要格式。

- Epytext

在历史上，类似javadoc的风格很流行，因此它被作为Epydoc(使用所谓的Epytext格式)生成文档的基础。

例子:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- - - - - -休息

现在，可能更流行的格式是reStructuredText (reST)格式，Sphinx使用它来生成文档。 注意:它在JetBrains PyCharm中默认使用(定义方法后输入三引号并按enter)。在Pyment中也默认使用它作为输出格式。

例子:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

——谷歌

谷歌有自己经常使用的格式。它也可以由狮身人面像(即。使用拿破仑插件)。

例子:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

还有更多例子

- 努皮多克

注意，Numpy建议遵循自己的基于谷歌的numpydoc格式，并由Sphinx使用。

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

转换/生成

可以使用像Pyment这样的工具自动为尚未记录的Python项目生成文档字符串，或者将现有的文档字符串(可以混合多种格式)从一种格式转换为另一种格式。

注意:示例取自Pyment文档

我建议使用Vladimir Keleshev的pep257 Python程序根据PEP-257和Numpy Docstring标准检查文档字符串，以描述参数，返回值等。

Pep257将报告您与标准的差异，并被称为pylint和pep8。