Python面向对象编程指南

第18章 质量和文档

好的软件不是偶然产生的而是精雕细琢出来的。一个可交付的产品包含可读的、准确的文档。我们会介绍两种从代码生成文档的工具：pydoc和Sphinx。如果使用一个轻量级的标记语法来编写文档，可以增强Sphinx工具的能力。我们会介绍一些ReStructured Text（RST）的功能来让文档的可读性更好。

文档是软件质量的一个重要方面，它是建立信任的其中一个方面。测试用例是建立信任的另外一种方法。用doctest编写测试用例同时达到了这两个质量要求。

我们还会简单介绍大纲式编程技术。这种技术的主要目的是编写漂亮的、容易理解的文档。同时，这个文档包含所有的带有注释和设计细节的源代码。大纲式编程不简单，但是它可以为我们带来高质量的代码和非常清晰、完整的文档。

18.1 为help()函数编写docstrings

Python为我们提供了许多地方可以编写文档。包、模块、类或者函数的定义中都包含一个描述被定义对象的字符串。在本书中，我们没有在任何例子中使用文档注释（docstrings），因为我们主要关注Python的编程细节，而不是需要交付的、完整的软件产品。

当我们开始学习高级面向对象设计技术并且关注整个可交付的产品时，文档注释就成为可交付产品中的一个重要部分了。文档注释可以为我们提供一些重要的信息。

• API：参数、返回值和抛出的异常。
• 对预期行为的描述。
• 可选的，提供doctest的测试结果。更多关于测试的信息，参见第15章“可测试性的设计”。

当然，我们可以在文档注释中包括更多的信息。我们可以提供关于设计、架构和需求的更多细节。在某些时候，这些更抽象、高级的问题和Python代码没有直接关系。这种高级设计和需求不属于代码或者文档注释。

help()函数提取并显示文档注释，它会对文本执行一些基本的格式化操作。 ...