编写DOCSTRINGS-指定函数参数并返回

Question

假设我有一个功能，说：

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

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

在DocString中指定需要A并返回A+1的约定是什么？

Answer 1

docstring的想法是为用户提供有关发生和出现的事情的基本概述，而无需告诉他们太多事情发生。在这种情况下：

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

对于一个不太琐碎的例子，我喜欢 潜入有关记录功能的Python部分：

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

    Return string."""

显然，更复杂的功能需要更大的docstring。只需确保docstring谈论正在发生的事情（正在通过的是什么，返回的是什么），而不是如何发生（不应包括实现细节）。

Answer 2

PEP 257 应该帮忙！

Answer 3

对于Python公约（关于此和其他主题），我建议首先尝试Python增强建议。

Python Pep 257 建议使用一行Docstrings指定您的功能：

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

但不是这样：

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

因为后一个示例可以通过其他手段来分散。

只瞥了一眼他们，但是佩普的链接看起来像是其他pep的链接，这些链接进入了docstrings的秘密。

总的来说，如果您还没有，我会浏览PEPS，因为有关Python设计决策和哲学的一些有趣的话题。

Answer 4

我个人喜欢内置的风格。

>>>帮助（LEN）

伦（...）

len(object) -> integer

Return the number of items of a sequence or mapping.