Mythical Man-Month, 人月神话

Ref

《人月神话》 Chapter 15 另外一面

15 另外一面

• 不了解就无法真正拥有
  *. 哦，赐予我朴素的评论者吧，他们不会因过于深奥而让人困惑不解。

• What we do not understand we do not prossess

• O give me commentators plain, Who with no deep researches vex the brain.

• Why ?

  • 记忆衰退，用户会失去对程序的了解
  • 公共应用程序的用户在时间和空间上远离程序的作者，因此文档的重要性不言而喻。其重要性，不亚于面向机器的的代码语言。

• How ?

  • Explain
    举办讲座向同事及新员工解释文档的重要性，旨在延长软件的生命周期，客服惰性和进度的压力。但均失败了。
  • Examples
    向同事们展示如何才能产生一篇优秀的文档上

15.1 需要什么样的文档

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

15.1.1 使用程序

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

15.1.2 验证程序

15.1.3 修改程序

15.2 流程图

15.3 自文档化的程序