第15章 另外一面

1.对于软件编程产品来说，程序向用户所呈现的面貌-文档，与提供给机器识别的内容同样重要。

2.即使是完全开发给自己使用的程序，描述性文字也是必需的，因为它们会被用户-作者所遗忘。

3.培训和管理人员基本上没有向编程人员成功地灌输对待文档的积极态度-文档能在整个生命周期对克服懒惰和进度的压力起促进和激励作用。

4.这样的失败并不都是因为缺乏热情或者说服力，而是没能正确地展示如何有效和经济地编制文档。

5.大多数文档只提供了很少的总结性内容。必须放慢脚步，稳妥地进行。

6.由于关键的用户文档包含了与软件相关的基本决策，因此它的绝大部分需要在程序编制之前书写。

7.每一份发布的程序拷贝应该包括一些测试用例，其中一部分用于校验输入数据，一部分用于边界输入数据，另一部分用于无效的输入数据。

8.对于必须修改程序的人而言，他们需要程序内部结构文档，同样要求一份清晰明了的概述。

9.流程图是被吹捧得最过分的一种程序文档。详细逐一记录的流程图是一件令人生厌的事情，而且高级语言的出现使它显得陈旧过时。

10.如果这样，很少有程序需要一页纸以上的流程图。

11.为了使文档易于维护，将它们合并至源程序是至关重要的，而不是作为独立文档进行保存。

12.最小化文档担负三个关键思路：

（1）借助那些必须存在的语句，如名称和声明等。来附加尽可能多的文档信息。

（2）使用空格和格式来表现从属和嵌套关系，提高程序的可读性。

（3）以段落注释，特别是模块标题的形式，向程序中插入必要的记述性文字。

13.程序修改人员所使用的文档，除了描述事情如何，还应阐述它为什么那样。对于加深理解，目的是非常关键的，即使是高级语言的语法，也不能表达目的。

14.在线系统的高级语言中，自文档化技术发现了它的绝佳应用和强大功能。