假设我有一个功能,比如说:
>>> def foo(a):
return a+1
我想为它写一个文档字符串。
在docstring中指定它需要a并返回+ 1?
的约定是什么答案 0 :(得分:7)
文档字符串的概念是为用户提供进出的内容的基本概述,而不会过多地告诉他们如何发生这种情况。在这种情况下:
def foo(a):
"""Take a number a and return its value incremented by 1."""
return a + 1
对于一个不太重要的例子,我喜欢Dive Into Python's section on documenting functions:
中的那个def build_connection_string(params):
"""Build a connection string from a dictionary of parameters.
Return string."""
显然,更复杂的功能需要更大的文档字符串。只需确保docstring正在讨论正在发生的事情(传递的是什么,返回的是什么)而不是如何发生(不应包括实现细节)。
答案 1 :(得分:3)
PEP 257应该有帮助!
答案 2 :(得分:3)
对于Python约定(关于这个和其他主题),我建议首先尝试Python增强建议。
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设计决策和哲学的有趣话题。
答案 3 :(得分:1)
我个人喜欢内置使用的风格。
>>>帮助(LEN)
LEN(...)
len(object) -> integer Return the number of items of a sequence or mapping.