一般来说，文档字符串应该只显示函数的输入和输出，并包括一个人类可读的函数 * 做什么 * 的描述。下面是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

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

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

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

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

有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自动为您做的事情。