18.10 总结

我们介绍了用下面4种方式创建可用的文档。

• 可以在文档注释包括一些软件的信息。
• 可以用pydoc从软件中提取API引用信息。
• 可以用Sphinx创建更复杂、更详细的文档。
• 同样地，可以用大纲式编程工具创建更深入、更有意义的文档。

设计要素和折中方案

我们应该将文档注释当作与其他Python源代码一样重要。它确保了help()函数和pydoc可以正常工作。和单元测试用例一样，文档注释应该被看作软件的必需组成部分。

Sphinx创建的文档可能具有非常好的外观，它将让我们可以并行地编写文档与代码。我们的目标一直是与其他的Python特性无缝集成。用Sphinx会为文档的获取和创建引入一个额外的目录结构。

随着我们设计不同的类，如何描述设计的问题几乎会变得和最后获得设计本身一样重要。如果软件无法快速清晰地解释，它通常会被视为不可信任。

花一些时间编写一份说明文档可能会发现一些隐藏的复杂性或者不合常规的行为。在这些情况下，我们可能不应该重构一个设计来修正漏洞或者提升性能，更应该做的是让软件变得更容易描述，可描述性是具有巨大价值的质量因素。