Python 函数/方法文档字符串变量

Question

假设我要为下面的代码编写文档字符串：

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

会是这样吗：

def some_thing_cool(age, name):
    """Something for bday
    
    Args:
         age (int) : age of bday person
         name (string) : name of bday person
    Variable:
             better_age (int) : age - 20 for more pleasing age
             cooler_name (string) : name + awesome
             bday_list (list) : things to remember for bday
    Returns:
            bday_list (list) : best to return the list
    """
    better_age = age - 20
    cooler_name = name + 'awesome'
    bday_list = ['cake', 'balloons']
    return bday_list

或者应该是这样的：

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

最重要的是，为什么要这样或那样？ （不要考虑文档字符串风格，这在这个问题中并不重要。） 我在网上找到的大多数示例在显示如何编写良好的文档字符串时不包含任何变量，这一直在我的脑海中。

Answer 1

一般来说，文档字符串应该只显示函数的输入和输出，并包含函数做什么的人类可读的描述。以下是来自 Python 文档字符串文档的示例：

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

将自己置于从未见过代码的读者的角度。如果我只是想使用您的函数，我真的关心其中使用的每个变量吗？我真的应该只关心它作为输入以及它提供什么作为输出。

Answer 2

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

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

文档字符串用于向想要使用该功能的人描述该功能。由于变量在函数外部不可用，因此函数的用户不会真正关心它们，它们只会弄乱文档字符串。您可以在代码中添加注释来描述变量的作用，以便任何阅读您代码的人都可以理解它。

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

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
    ...

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

def get_versions(self, db_id):
    """ Simple call to look up all versions in a jira project
    :param db_id:   int: The ID of the Jira project
    :return:        list: of version objects
    :raises:        JIRAError on failure
    """
    ...

这几乎就是 PyCharm 自动为您做的事情......