Python函数/方法docstring变量

Question

假设我要为下面的代码编写docstring：

def some_thing_cool(age, name):
    better_age = age - 20
    cooler_name = name + 'awesome'
    bday_list = ['cake', 'balloons']
    return bday_list

会是这样吗：

^{pr2}$

还是应该这样：

def some_thing_cool(age, name):
    """Something for bday

    Args:
         age (int) : age of bday person
         name (string) : name of bday person
    Returns:
            bday_list (list) : best to return the list
    """
    better_age = age - 20
    cooler_name = name + 'awesome'
    bday_list = ['cake', 'balloons']
    return bday_list

最重要的是为什么要这样或那样？ （不要考虑docstring样式，这在这个问题中并不重要。） 我在网上找到的大多数例子在展示如何编写好的docstring时没有包含任何变量，这一直在我脑海中浮现。在

Answer 1

这些变量在函数之外不可用：

def some_thing_cool(age, name):
    better_age = age - 20 #this is a better age
    cooler_name = name + 'awesome' #This name is better (spaces not included)
    bday_list = ['cake', 'balloons']
    return bday_list

returnedValue = some_thing_cool(31.4159, 'Will')
#sets returned value equal to ['cake', 'balloons']

print(better_age) #NameError: name 'better_age' is not defined

Doc字符串用于向想要使用它的人描述函数。由于变量在函数之外不可用，因此函数的用户不会真正关心它们，它们只是把docstring弄得一团糟。您可以在代码中添加注释来描述变量的作用，以便任何阅读您代码的人都能理解它。在

变量不可用的原因是由于名称空间，您可能需要查看它们。在

Answer 2

我已经指出，这主要是基于意见的，但一般来说，docstrings应该只显示函数的输入和输出，并包括一个人类可读的函数的作用的描述。下面是一个来自Python docstring documentation的示例：

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real   the real part (default 0.0)
    imag   the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero

把你自己放在一个从未见过代码的读者的角度。如果我只是想使用你的函数，我真的关心它里面使用的每个变量吗？我真的应该只关心它把什么作为输入，它提供什么作为输出。在

最后，请注意，在堆栈溢出时，问题不应主要基于意见，因为它们往往会吸引大量的答案，而这些答案并不能证明是对是错。签出How To Ask。在

Answer 3

有PEP-257，但我个人认为不够详细

政治公众人物：

def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real   the real part (default 0.0)
    imag   the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

我个人在代码中使用以下约定

^{pr2}$

这几乎就是PyCharm自动为你做的。。。在