Python交互设计_文档字符串_调试

一，文档字符串

文档字符串，指在函数开头部位，解释函数的交互接口的字符串，doc是文档documentation的缩写。下面是一个例子:

$ cat a.py

#!/bin/python

def polyline(t, n, length, angle):

    """         #注意这里要缩进

    Draws n line segments with the given length and t is a turtle.

    """

for i in range(n):

      t.fd(length)

      t.lt(angle)

一般情况下，所有文档字符串都是三重引用字符串，也被叫做多行字符串，因为三重的单引号表示允许这个字符串是多行的。

这些文字很简洁，但都包含了一些关键的信息，这些信息对于函数使用者来说至关重要。这些信息简要解释了函数的用途(不会说细节，也不会说如何实现)。

文档解释了每个参数对函数行为的影响，以及各自的类型(一般在不是显而易见的情况下就需要给解释)。

写这种文档，对交互接口的设计来说，是至关重要的。

设计良好的交互接口应该很容易解释明白；如果你的函数有一个特别不好解释了，估计这个函数的交互设计还存在需要改进的地方。

二，调试

一个交互接口，就像是函数和调用者的一个中间人。调用者提供特定的参数，函数完成特定的任务。

例如，polyline这个多段线函数，需要四个实际参数:

t必须是一个Turtle小乌龟；n(边数)必须是一个整形；length(长度)应该是一个正数；angle(角度)必须是一个以度为单位的角度值。

这些要求叫做【前置条件】，因为要在函数开始运行之前就要实现才行。

相应的在函数结尾那里的条件叫【后置条件】，后置条件包含函数的预期效果(如画线段)和其他作用(如移动小箭头或进行其他改动)。

前置条件是准备给函数调用者的。如果调用者违背了(妥当标注的)前置条件，然后函数不能正常工作，这个bug就会反馈在函数调用者上，而不是函数本身。

如果前置条件得到了满足，而后置条件未能满足，这个bug就是函数的了。所以如果你把前置条件、后置条件都弄清晰，对调试很有帮助。

结束。