《人月神话》（P15）另外一面

前言

• 初级的程序员写机器能看懂的语言，高级程序员写人类能看懂的语言。
• 即便是完全开发给自己使用的程序，这种书面的沟通也是必要的，因为它会被用户（作者）所遗忘。
• 程序向用户所呈现的面貌与提供给机器识别的内容同样重要，需要把重点放在“如何做”才能产生一篇优秀的文档。

需要什么样的文档

• 培训和管理人员基本上没有面向编程人员成功的灌输对文档的积极态度——文档在整个生命周期对克服懒惰和进度压力起到促进和激励的作用。
• 这样的失败并不都是缺乏热情或者说服力，而是没能正确的展示如何有效和经济的编制文档。
• 大多数文档只提供了很少的总结性内容。必须放慢脚步，稳妥的进行。

关键的文档包括了与软件相关的基本决策，绝大部分内容需要在编程之前书写：

1. 目的。主要功能是什么？开发程序的原因是什么？
2. 环境。 程序运行在什么机器、硬件配置和操作系统上？
3. 实现功能和使用的算法。精确的阐述它做了什么。
4. 选项。用户的功能选项有哪些？如何在选项之间进行挑选？
5. 输入-输出格式。必须是确切完整的。

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

对于必须修改程序的人而言，他们需要程序内部结构文档，同样要求一份清晰明了的概述，它包括了5项内容：

1. 流程图或子系统结构图。
2. 对所用算法的完整描述，或者是类似算法的参考资料。
3. 对所有文件规划的解释。
4. 数据流处理的概要描述。
5. 初始设计中，对已预见修改的讨论：特性、功能回调以及出口的位置。原作者对于可能修改的地方以及可能处理的方案的一些建议。另外，对隐藏缺陷的观察也同样有价值。

流程图

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

自文档化的程序

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

最小化文档的三个关键思路：

1. 借助那些必须存在的语句，例如名称和声明等，来附加尽可能多的文档信息。
2. 使用空格和格式来表现从属关系，提高程序的可读性。
3. 以段落注释，特别是模块标题的形式，向程序中插入必要的记叙性文字。

• 程序修改人员所使用的文档中，除了描述事情如何，还应该阐述为什么要那样做。对于加深理解，目的是非常关键的，即使再高级的语言，也不能表达目的。
• 自文档技术将被大范围应用。

以上就是《人月神话》第15章——另外一面的全部内容

本章中，作者展开描述了文档中的各种细节，现在来看，观点无疑是非常超前的。

书写文档并不是上级领导要求程序员的工作，而是整个团队应该共同完成的必要步骤。管理人员首先是应该意识到文档的必要性，其次还应该正确的展示如何有效和经济的编制文档，否则一件连自己都不认同、做不好的事情，团队如何跟着你一起做呢？

文档结构的规范是管理者需要关注的，出发点应该是“编程人员如何以最少的投入，获得最好的效果”。从这个角度来说，文档的结构是变化的，根据行业、项目大小、功能特点、团队组成来制定是比较合理的，具体怎样就依赖于管理者的经验了。