人月神话读书笔记（15）----另外一面

另外一面

---

英国巨石阵是世界上最大的没有文档说明的“计算机器“。4000－5000年前古人没有留下只言片语说明巨石阵的用途，至今考古学家对古人建筑巨石阵的目的莫衷一是。
比喻文档匮乏会使软件产品难以为用户接受，故而使用文档在软件项目中相当重要。

对软件编程产品来说，程序向用户呈现的（文档）和提供给机器识别的内容同样重要。

需要什么样的文档

1. 每个用户都需要一段对程序进行描述的文字。可是大数文档只提供了很少的总结性内容，无法达到用户要求。为了得到一份有用的文字描述，就必须放慢脚步，稳妥地进行；
2. 每一份发布的程序拷贝应该包括一些可以例行运行的小测试用例，用用户提供信心；
3. 对于必须修改程序的人而言，他们需要程序内部结构文档，同样要求一份清晰明了的概述；

流程图

1. 流程图是被吹捧得最过分的一种程序文档。很少有程序需要一页纸以上的流程图；

自文档化的程序

1. 合并文件，即把文档整合到源程序。这对正确维护是直接有力的推动，保证编程用户能方便、及时地得到文档资料；
2. 文档是通过程序结构、命名和格式来实现的，所有这些必须在第一次书写代码时完成；