《像计算机科学家一样思考Python》——4.9　文档字符串

本节书摘来自异步社区《像计算机科学家一样思考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)

这里的文档字符串是一个使用三引号括起来的字符串。三引号字符串又称为多行字符串，因为三引号允许字符串跨行表示。

文档字符串很简洁，但已经包含了其他人需要知道的关于函数的基本信息。它精确地解释了函数是做什么的（而不会涉及它是如何实现的细节）。它解释了每个形参对函数行为的影响效果以及每个形参应有的类型（如果其类型并不显而易见）。

编写这类文档是接口设计的重要部分。一个设计良好的接口，也应当很简单就能解释清楚；如果你发现解释一个函数很困难，很可能表示它的接口设计有改进的空间。