为什么流程图是被吹捧得最过分的程序文档？
- 事实: 很多程序甚至不需要流程图, 很少有程序需要一页纸以上的流程图;
- 局限: 流程图只显示程序的判断流向, 仅仅是程序结构的一个方面;
- 拆分即破坏: 当流程图分成几张、需要编号出口和连接符拼装时, 整体结构的概观被严重破坏;
- 合理用法: 一页纸的流程图是表达程序结构、阶段或步骤的一种非常基本的图示, 也非常容易绘制;
- 历史定位: 流程图是 Goldstine 和 Neumann 引入的高级控制语言, 用来把机器语言组合成可理解的步骤;
- 消失的路径: 高级语言中分组已完成 → 每个方框对应一条语句 → 方框变成单调重复 → 箭头也冗余 → 用块结构消除
GO TO 后箭头全部消失;
- 现实观察: 没有有经验的编程人员在编写程序之前会例行公事地绘制详尽流程图; 要求流程图的组织中, 流程图总是事后补上;
- 作者判断: 这不是令人尴尬的实践偏离, 而是对技术的良好评判; 对新编程人员不应强加陈旧的流程图方法;
什么是自文档化的程序？
- 原则来源: 数据处理的基本原理--把信息放在不同文件中并努力维持同步, 是非常费力不讨好的事情;
- 违反原则的现状: 实践中试图维护一份机器可读的程序, 以及一系列包含记叙性文字和流程图的文档;
- 后果: 程序文档质量声名狼藉, 文档维护低劣, 程序变动总不能及时精确地反映在文档中;
- 解决方案: "合并文件"--把文档整合到源代码;
- 收益: 对正确维护是直接有力的推动, 保证编程用户能方便、即时地得到文档资料;
- 约束: 把源程序作为文档介质强制推行了一些约束（格式、命名、注释风格）;
如何做到自文档化？
- 方法一（借语句表达）: 借助语言要求必须存在的语句附加尽可能多的文档信息--标签、声明语句、符号名称;
- 方法二（格式）: 尽可能使用空格和一致的格式提高可读性, 表现从属和嵌套关系;
- 方法三（段落注释）: 以段落注释形式插入必要的记叙性文字, 提供总体把握, 加深读者理解;
- 具体技巧（12 条中的代表）:
- 为每次运算使用单独的任务名称, 维护记录目的、时间和结果的日志;
- 程序名称包含版本号并帮助记忆;
- 在过程注释中写记叙性描述;
- 为基本算法提供参考引用, 允许有经验的读者跳过;
- 声明所有变量, 用助记符并用注释把声明补成完整说明;
- 用标签标记初始化位置;
- 对语句分组和标记, 显示与设计文档中语句单元的一致性;
- 利用缩进表现结构和分组;
- 用行注释解释不很清楚的事情;
- 把多条语句放在一行或把一条语句拆开, 以吻合逻辑思维;
自文档化有哪些反对意见和回应？
- 反对一（源代码规模增加）: 作者发现自己写的 APL 程序注释比 PL/I 少, 因为 APL 保存在磁盘上而 PL/I 以卡片存储;
- 回应一: 文本编辑和存储都在向在线方向发展; 程序和文字混合使用减少了需要存储的字符总数;
- 反对二（击键更多）: 用打字方式, 每份草稿每个字符至少一次击键;
- 回应二: 自文档化程序字符总数更少, 每字符击键次数更少, 且电子草稿不需重复打印;
- 反对三（流程图和结构图怎么办）: 若只使用最高级别的结构图, 另外使用一份文档可能更安全, 因为结构通常不会频繁变化;
- 适用范围: 自文档化方法的基本思想可大规模应用; 空间和格式要求较严格的部分应用可能受限; 命名和结构化声明显然可以利用, 宏可提供帮助; 段落注释在任何语言中都是很棒的实践;