Python文档字符串
Python有一个叫文档字符串(documentation strings)的好特性,通常用缩写名docstrings来指定。 文档字符串是你应该使用的一个重要工具,它对程序文档有助,令其容易理解。令人惊讶的是,当程序实际运行时,我们甚至可以从例如一个函数返回文档字符串。
文档字符串举例:
5 最大
打印两个数中的最大值。
两个值必须是整数。
它是如何工作的:
函数的第一个逻辑行的字符串是那个函数的文档字符串。注意,文档字符串也适用于在各自 的章节将要学习的模块和(类)(#面向对象的程序设计)。
文档的以贯例是多行字符串,第一行以大写字母开头以句点(.)结束(注:中文在V3.3中也可以),第二行是空行,从第三行开始是详细描述。强烈建议,为你重要的函数写文档字符串要遵循此贯例。
我们可以使用函数的__doc__(注意,双下划线)属性(属于名字的)访问printMax函数的文档字符串。只要记住,Python把一切任何事情作为一个对象对待,这也包括函数。我们将在类这一章学习关于对象的更多知识。
如果你在Python中已经使用过help(),那么你已经看到如何使用文档字符串了!它所做的仅仅是获取函数的 __doc__ 属性,并以一个整洁的方式显示给你。你可以在上面的函数——在你的程序中仅包括help(printMax)尝试一下。记得按下q键,退出help。
自动化工具可以从你的程序中以这种方式检索文档。因此,我强烈建议,为你写的任何重要函数使用文档字符串。来自Python的自动化工具pydoc命令使用文档字符串的工作原理类似于help()。
文档字符串举例:
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()。