人月神话--另外一面

不了解，就无法真正拥有。——歌德

书面的计算机程序还有其他的呈现面貌：向用户诉说自己的“故事”。即使是完全 开发给自己使用的程序，这种沟通仍然是必要的。因为记忆衰退的规律会使用户－作者失去 对程序的了解，于是他不得不重拾自己劳动的各个细节。

面对那些文档“简约”的程序，我们中的大多数人都不免曾经暗骂那些远在他方的匿 名作者。因此，一些人试图向新人慢慢地灌输文档的重要性：旨在延长软件的生命期、克服 惰性和进度的压力。但是，很多次尝试都失败了，我想很可能是由于我们使用了错误的方法。

如何做（才能产生一篇优秀的文 档）？

不同用户需要不同级别的文档。某些用户仅仅偶尔使用程序，有些用户必须依赖程序， 还有一些用户必须根据环境和目的的变动对程序进行修改。

使用程序

验证程序

修改程序

流程图是被吹捧得最过分的一种程序文档。事实上，很多程序甚至不需要流程图，很 少有程序需要一页纸以上的流程图。

流程图显示了程序的流程判断结构，它仅仅是程序结构的一个方面。

当流程图绘制在 一张图上时，它能非常优雅地显示程序的判断流向，但当它被分成几张时，也就是说需要采 用经过编号的出口和连接符来进行拼装时，整体结构的概观就严重地被破坏了。

现实中，流程图被鼓吹的程度远大于它们的实际作用。我从来没有看到过一个有经验 的编程人员，在开始编写程序之前，会例行公事地绘制详尽的流程图。在一些要求流程图的 组织中，流程图总是事后才补上。

不同文件的数据保存带来了不良的后果。程序文档质 量声名狼藉，文档的维护更是低劣：程序变动总是不能及时精确地反映在文档中。

我认为上述问题相应的解决方案是“合并文件”，即把文档整合到源代码。

文档是我们以及前人都不曾成功背负的重担。作为基本目标，我们必须试图把它的负 担降到最小。

方法

技巧

““自文档化”方法”对空间和格式要求更为严格， 这一点的应用可能会受限；而命名和结构化声明显然可以利用起来，在这方面，宏可以起到 很大的帮助；另外，段落注释的广泛使用在任何语言中都是一个很棒的实践。