不了解，就无法真正拥有

需要什么样的文档

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

使用程序。

  1. 目的。主要的功能是什么？开发程序的原因是什么？
  2. 环境。程序运行在什么样的机器、硬件配置和操作系统上？
  3. 范围。输入的有效范围是什么？允许显示的合法范围是什么？
  4. 实现功能和使用的算法。精确地阐述它做了什么。
  5. 输入－输出格式。必须是确切和完整的。
  6. 操作指令。包括控制台及输出内容中正常和异常结束的行为。
  7. 选项。用户的功能选项有哪些？如何在选项之间进行挑选？
  8. 运行时间。在指定的配置下，解决特定规模问题所需要的时间？
  9. 精度和校验。期望结果的精确程度？如何进行精度的检测？

验证程序。

  1. 针对遇到的大多数常规数据和程序主要功能进行测试的用例。它们是测试用例的主要组成部分。
  2. 数量相对较少的合法数据测试用例，对输入数据范围边界进行检查，确保最大可能值、最小可能值和其他有效特殊数据可以正常工作。
  3. 数量相对较少的非法数据测试用例，在边界外检查数据范围边界，确保无效的输入能有正确的数据诊断提示。

修改程序。

  1. 流程图或子系统的结构图，对此以下有更详细的论述。
  2. 对所用算法的完整描述，或者是对文档中类似描述的引用。
  3. 对所有文件规划的解释。
  4. 数据流的概要描述——从磁盘或者磁带中，获取数据或程序处理的序列——以及在
    每个处理过程完成的操作。
  5. 初始设计中，对已预见修改的讨论；特性、功能回调的位置以及出口；原作者对可
    能会扩充的地方以及可能处理方案的一些意见。另外，对隐藏缺陷的观察也同样很有价值。

流程图

对于新的编程人员和陈旧的流程图方法，我持有相同的观点。

自文档化（self-documenting）的程序

技巧

  1. 为每次运算使用单独的任务名称

  2. 使用包含版本号和能帮助记忆的程序名称。

  3. 在过程（PROCEDURE）的注释中，包含记叙性的描述文字。

  4. 尽可能为基本算法提供参考引用，通常它会指向更完备的处理方法。这样，既节省了空间，同时还允许那些有经验的读者能非常自信地略过这一段内容。

  5. 显示和算法书籍中的传统算法的关系。

    1. a) 更改 b) 定制细化 c) 重新表达

  6. 声明所有的变量。采用助记符，并使用注释把 DECLARE 转化成完整的说明

  7. 用标签标记出初始化的位置。

  8. 对程序语句进行分组和标记，以显示与设计文档中语句单元的一致性

  9. 利用缩进表现结构和分组。

  10. 在程序列表中，手工添加逻辑箭头。

  11. 使用行注释来解释任何不很清楚的事情。

  12. 把多条语句放置在一行，或者把一条语句拆放在若干行，以吻合逻辑思维，表示和其他算法描述一致。

  自文档化方法激发了高级语言的使用，特别是用于在线系统的高级语言——无论是对批处理还是交互式，它都表现出最强的功效和应用的理由。如同我曾经提到的，上述语言和系统强有力地帮助了编程人员。因为是机器为人服务，而不是人为机器服务。因此从各个方面而言，无论是从经济上还是从以人为本的角度来说，它们的应用都是非常合情合理的。