python的DocStrings

简介：

Python 有一个甚是优美的功能称作文档字符串（Documentation Strings），在称呼它时通常会使用另一个短一些的名字docstrings。
DocStrings 是一款你应当使用的重要工具，它能够帮助你更好地记录程序并让其更加易于理解。令人惊叹的是，当程序实际运行时，我们甚至可以通过一个函数来获取文档！

案例

def print_max(x, y):
    '''Prints the maximum of two numbers.打印两个数值中的最大数。

    The two values must be integers.这两个数都应该是整数'''
    # 如果可能，将其转换至整数类型
    x = int(x)
    y = int(y)

    if x > y:
        print(x, 'is maximum')
    else:
        print(y, 'is maximum')

print_max(3, 5)
print(print_max.__doc__)

运行结果：

它是如何工作的

函数的第一行逻辑行中的字符串是该函数的 文档字符串（DocString）。这里要注意文档字符串也适用于后面相关章节将提到的模块（Modules）与类（Class） 。

该文档字符串所约定的是一串多行字符串，其中第一行以某一大写字母开始，以句号结束。第二行为空行，后跟的第三行开始是任何详细的解释说明。在此强烈建议你在你所有重要功能的所有文档字符串中都遵循这一约定。

我们可以通过使用函数的 doc （注意其中的双下划綫）属性（属于函数的名称）来获取函数 print_max 的文档字符串属性。只消记住 Python 将所有东西都视为一个对象，这其中自然包括函数。我们将在后面的类（Class）章节讨论有关对象的更多细节。

如果你曾使用过 Python 的 help() 函数，那么你应该已经了解了文档字符串的用途了。它所做的便是获取函数的 doc 属性并以一种整洁的方式将其呈现给你。你可以在上方的函数中尝试一下——只需在程序中包含 help(print_max) 就行了。要记住你可以通过按下 q 键来退出 help 。

自动化工具可以以这种方式检索你的程序中的文档。因此，**我强烈推荐你为你编写的所有重要的函数配以文档字符串。**你的 Python 发行版中附带的 pydoc 命令与 help() 使用文档字符串的方式类似。

删除线格式 删除线格式 删除线格式 删除线格式

第10章 函数