DocStrings语句

Python有一个漂亮的功能，称为文档字符串，通常用它的简称docstrings来指代。DocStrings是您应该使用的重要工具，因为它有助于更​​好地记录程序并使其易于理解。令人惊讶的是，甚至在程序实际运行时，我们甚至可以从函数中获取文档字符串！

示例（另存为function_docstring.py）：

def print_max(x, y):
    '''Prints the maximum of two numbers.

    The two values must be integers.'''
    # convert to integers, if possible
    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__)

输出：

$ python function_docstring.py
5 is maximum
Prints the maximum of two numbers.

    The two values must be integers.

这个怎么运作

函数第一逻辑行上的字符串是该函数的文档字符串。请注意，DocStrings也适用于我们将在相应章节中学习的模块和类。

文档字符串遵循的约定是多行字符串，其中第一行以大写字母开头，以点结束。然后，第二行是空白，然后是从第三行开始的任何详细说明。你是强烈建议遵循这一惯例所有的文档字符串为您的所有非普通功能。

我们可以使用print_max函数的__doc__（请注意双下划线）属性（名称属于）来访问函数的文档字符串。请记住，Python将所有内容都视为对象，并且其中包括函数。我们将在有关类的一章中学习有关对象的更多信息。

如果您使用help()过Python，那么您已经看到了docstrings的用法！它所做的只是获取该__doc__函数的属性，并以整洁的方式为您显示它。您可以在上面的功能上尝试一下-仅包含help(print_max)在您的程序中。记住q按键退出help。

自动化工具可以通过这种方式从您的程序中检索文档。因此，我强烈建议您将docstrings用于编写的所有非平凡函数。pydocPython发行版随附的命令的工作方式与help()使用docstrings相似。

概括

我们已经看到了很多方面的功能，但是请注意，我们仍然没有涵盖所有方面。但是，我们已经涵盖了您每天都会使用的与Python函数有关的大部分内容。