Python文档字符串

2023年9月14日 344次阅读

Python有一个叫
文档字符串（documentation strings）的好特性，通常用缩写名docstrings来指定。 文档字符串是你应该使用的一个重要工具，它对程序文档有助，令其容易理解。令人惊讶的是，当程序实际运行时，我们甚至可以从例如一个函数返回文档字符串。

文档字符串举例：

def printMax(x, y):
    '''打印两个数中的最大值。
    两个值必须是整数。'''
    x = int(x) # 如果可能，转换为整数
    y = int(y)

    if x > y:
        print(x, '最大')
    else:
        print(y, '最大')

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

输出：

5 最大

打印两个数中的最大值。

            两个值必须是整数。

它是如何工作的：

函数的第一个逻辑行的字符串是那个函数的文档字符串。注意，文档字符串也适用于在各自 的章节将要学习的模块和(类)(#面向对象的程序设计)。

文档的以贯例是多行字符串，第一行以大写字母开头以句点(.)结束(注：中文在V3.3中也可以)，第二行是空行，从第三行开始是详细描述。强烈建议，为你重要的函数写文档字符串要遵循此贯例。

我们可以使用函数的__doc__(注意，双下划线)属性(属于名字的)访问printMax函数的文档字符串。只要记住，Python把一切任何事情作为一个对象对待，这也包括函数。我们将在类这一章学习关于对象的更多知识。

如果你在Python中已经使用过help()，那么你已经看到如何使用文档字符串了!它所做的仅仅是获取函数的 __doc__ 属性，并以一个整洁的方式显示给你。你可以在上面的函数——在你的程序中仅包括help(printMax)尝试一下。记得按下q键，退出help。

自动化工具可以从你的程序中以这种方式检索文档。因此，我强烈建议，为你写的任何重要函数使用文档字符串。来自Python的自动化工具pydoc命令使用文档字符串的工作原理类似于help()。

点赞