本节书摘来自异步社区《像计算机科学家一样思考Python》一书中的第4章,第4.9节,作者[美]Allen B. Downey,赵普明 译,更多章节内容可以访问云栖社区“异步社区”公众号查看。
4.9 文档字符串
文档字符串(docstring)是在函数开头用来解释其接口的字符串(doc是“文档”documentation的缩写)。下面是一个示例:
def polyline(t, n, length, angle):
"""Draws n line segments with the given length and
angle (in degrees) between them. t is a turtle.
"""
for i in range(n):
fd(t, length)
lt(t, angle)
这里的文档字符串是一个使用三引号括起来的字符串。三引号字符串又称为多行字符串,因为三引号允许字符串跨行表示。
文档字符串很简洁,但已经包含了其他人需要知道的关于函数的基本信息。它精确地解释了函数是做什么的(而不会涉及它是如何实现的细节)。它解释了每个形参对函数行为的影响效果以及每个形参应有的类型(如果其类型并不显而易见)。
编写这类文档是接口设计的重要部分。一个设计良好的接口,也应当很简单就能解释清楚;如果你发现解释一个函数很困难,很可能表示它的接口设计有改进的空间。