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

  1. 云栖社区>
  2. 博客>
  3. 正文

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

异步社区 2017-05-02 16:47:00 浏览849
展开阅读全文

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

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

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

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

网友评论

登录后评论
0/500
评论
异步社区
+ 关注