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

【问题标题】：Python function/method docstring variablesPython 函数/方法文档字符串变量
【发布时间】：2018-07-24 22:23:42
【问题描述】：

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

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

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

【问题讨论】：

我无法想象你为什么要记录函数的内部变量。重点是什么？它们是内部的，它们被称为什么或它们做什么与任何人无关。
如果你真的需要指定参数和返回值的类型，不要使用像string这样虚构的错误定义类型，使用你在类型注释中使用的实际名称，例如str。而且，理想情况下，List[str] 而不仅仅是 list，因为仅仅知道它返回一个 something 的列表并没有多大帮助。
更重要的是，只是重复名称和类型作为描述根本没有帮助。我已经知道age 是一个年龄，name 是一个名字，而bday_list 是“返回列表”......也许告诉我bday_list 是“生日派对的装饰品”或其他我不能的东西'否则不看源代码就知道了。
补充@DanielRoseman 所说的：如果您确实需要记录内部变量的作用，那么您是在为阅读内部实现的人而不是为人们记录它阅读 API 规范（无论是在此处还是在 Sphinx 生成的网页中）。因此，这应该作为源代码中的内联 cmets。

标签： python python-3.x python-2.7 docstring

【解决方案1】：

我已将其标记为主要基于意见，但一般来说，文档字符串应仅显示函数的输入和输出，并包含对函数作用的人类可读描述。这是来自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

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

最后，请注意，在 Stack Overflow 上，问题不应主要基于意见，因为它们往往会吸引大量无法证明是对或错的答案。查看How To Ask。

【讨论】：

刚刚发布了一个类似的迭代，并同意问题的基于意见的性质。变量的文档分散了文档字符串的目的，即描述功能，而不是内部状态/值。

【解决方案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

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

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

【讨论】：

【解决方案3】：

嗯，有PEP-257，但我个人认为不够冗长

来自 PEP：

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 自动为你做的事情......

【讨论】：