人月神话-另外一面

最后一章仍然在讲文档和文档有效性的问题。在开始就指出，我曾经非常勤奋地给我的软件工程师们举办了多年关于文档必要性以及优秀文档所应具备特点方面的讲座，向他们讲述——甚至是热诚地向他们劝诫以上的观点。不过，这些都行不通。我想他们知道如何正确地编写文档，却缺乏工作的热情。所以这章重点仍然放在了如何写文档，文档应该包含哪些核心要素上面。

不同用户需要不同级别的文档。某些用户仅仅偶尔使用程序，有些用户必须依赖程序，还有一些用户必须根据环境和目的的变动对程序进行修改。 在需要什么样的文档一段从使用程序，验证程序和修改程序三个方面来谈如何写文档，文档内容应该包含哪些核心要素。使用程序方面的文档发生在程序编写前，要描述清楚程序的目的，范围，场景，输入，输出等各项重要内容。每一个发布的程序需要附加验证说明，即准备我们常做的测试用例，这个发生在验证测试阶段。最后，调整程序或者修复程序需要更多的信息。显然，这要求了解全部的细节，并且这些细节已经记录在注释良好的列表中。

流程图是被吹捧得最过分的一种程序文档。事实上，很多程序甚至不需要流程图，很少有程序需要一页纸以上的流程图。现实中，流程图被鼓吹的程度远大于它们的实际作用。我从来没有看到过一个有经验的编程人员，在开始编写程序之前，会例行公事地绘制详尽的流程图。在一些要求流程图的组织中，流程图总是事后才补上。 (在这里我们需要重点强调的就是流程图和各种形式化的表达方式更多应该是应用在构思和前期需求阶段，真正到了设计开发阶段的时候往往并不需要复杂完整的流程图。)

最后谈到了自文档化程序，什么意思呢？核心思想仍然是程序本身应该是可以自解释的，详细的可以看《源代码即设计》一文。在这里有两个重要的阶段，很多时候详细设计可以省略掉，我们的重要设计思路会体现到我们的程序注释中，再进一步很多垃圾无用的代码注释也要去掉， 因为代码写好了，代码本身应该具备自解释能力。在源代码编写规范中谈到的注释，空行，缩进，变量命名，循环都有标准的编写规范，如果我们还能多考虑代码的复用和拆分，整个代码文件就能够有很强的可读性。