第四章：写可测试的文档

文档代码被认为是一件很难做到的事情。一方面，可扩展的、有深度的文档代码对其他程序员使用你的代码大有益处。它可以提供调用API的例子，或者解释代码为什么这样设计。而另一方面，随着代码的迭代，文档却很快的过时，变的毫无作用。

幸运的时，现在有个折中的办法，文档不需要弄成巨大的文档文件或者网站，它可以是小的文档（一页网页或者wiki）、函数的doc string、代码里面注释、最重要的是——代码本身的结合。如果你始终安好一个好的习惯编码，比如清晰的命名约定，一致的风格使用，你可以让你的注释和文档保持在一个非常小的数量级上。秉承一个好的编码风格，会让你不需要对对代码做额外注释，就非常清晰他的作用。当然这不是说注释和doc string就一无是处～其实，他们应该被节制的使用。只有在下列这些重要的地方使用他们，比如一个复杂的函数、解释一些代码为什么非得这么写、简单的提供一些信息而这些信息在你的代码或者函数命名里面无法表达出来的时候。保持你的注释数量较少，你可以避免过时的文档。不多的需要注释的地方会让你的工作变的简单。

但是，如果你还可以再进一步呢？正在的拥有动态的文档，它可以测试你所描述的函数？如果你将这些测试构建到你的代码里面，一旦函数发生改变，文档测试失败而强迫你去更改文档呢？这正是python的doctest库所能提供的。这章让你熟悉写文档测试，把他们结合到日常的工作流程中，并把它们加到你的工具箱中。