3

假设我有一个函数,比如说:

>>> def foo(a):
        return a+1

我想为它写一个文档字符串。

在文档字符串中指定它接受 a 并返回 a+1 的约定是什么?

4

4 回答 4

7

文档字符串的想法是让用户对正在发生的事情有一个基本的概述,而不会告诉他们太多关于这是如何发生的。在这种情况下:

def foo(a):
    """Take a number a and return its value incremented by 1."""
    return a + 1

举一个不那么简单的例子,我喜欢Dive Into Python 的文档函数部分中的那个:

def build_connection_string(params):
    """Build a connection string from a dictionary of parameters.

    Return string."""

显然,更复杂的函数需要更大的文档字符串。只需确保文档字符串正在谈论正在发生的事情(传入的内容,返回的内容)而不是如何发生的(不应该包括实现细节)。

于 2010-12-24T05:49:15.473 回答
3

PEP 257应该会有所帮助!

于 2010-12-24T05:47:26.207 回答
3

对于 Python 约定(关于这个和其他主题),我建议首先尝试 Python Enhancement Proposals。

Python PEP 257建议使用一行文档字符串来指定您的函数,如下所示:

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

但不是这样:

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

因为后一个例子可以通过其他方式来预测。

只是浏览了一下,但来自 PEP 的链接看起来会指向其他 PEP,这些 PEP 会进入文档字符串的本质。

作为一般说明,如果您还没有,我会浏览 PEP,因为有一些关于 Python 设计决策和哲学的有趣主题。

于 2010-12-24T05:51:02.130 回答
1

我个人喜欢内置函数使用的风格。

>>> 帮助(len)

伦(...)

len(object) -> integer

Return the number of items of a sequence or mapping.
于 2010-12-24T07:06:11.180 回答