提升软件可维护性的途径一使用适当的文档

• 不断强化流程文档到重量级的流程文档，到精简流程和文档，到几乎没有什么明确的流程和文档格式。
• 适当的文档增强软件的可理解性，帮助理解代码，软件不仅包括代码，还包括相关文档
• 文档的作用，记录信息，辅助沟通，帮助自己理清思路，帮助理解代码。
• 文档包括，可行性研究报告，需求文档，概要设计文档，架构设计文档，详细设计，接口设计，用户手册/使用说明书

1 文档类型

• 需求文档

  • 详尽记录每一条需求

  • 长期维护，时刻保持更新，是必须的文档

  • 使用者: 客户，市场人员，系统工程师，软件工程师，测试人员，维护人员。

  • 用户需求和系统需求

    • 用户需求，用户提出的最原始的需求，模糊，笼统。例如 ATM 机， 取钱，查询余额
    • 系统需求，对用户需求进行归纳总结，清晰话，具体话(需求分析)，包含用例分析，用户如何使用系统的。
      • 例如取钱的步骤：1) 用户插入银行卡，2)ATM 机读取磁条信息，3)用户输入密码，4) AMT 机吐出钞票
    • 需求分析，把用户需求转化为系统需求，获取和澄清用户需要， 是一个过程(需求迭代)，一个重要的内容是用例分析。
      • 用例分析，包括用例图，用户使用系统的方法步骤

• 测试用例文档

  • 跟踪每一条需求，描述详细测试步骤，
  • 长期维护，时刻保持更新，必须的文档
  • 使用人员，系统工程师，软件工程师，测试人员，维护人员

• 架构设计文档

  • 只放 high level/框架性的东西，以及核心业务逻辑， 稳定的东西，不深入细节，否则维护成本高，与实际实现适当同步，对于大型复杂系统几乎是必须的。

• 概要设计文档

  • 围绕功能实现，描述系统有哪些模块以及模块之间的关系，有哪些核心的类，及其之间的关系(类图)；用顺序图描述事件流 (通过对象的交互完成系统功能)；得到的类图和顺序图有待进一步细化(在详细设计或编码时)。
  • 不深入细节，不必同步更新(实现有变化时，有架构设计文档时)，不必长期维护，中间产品，用完就丢弃；非必须(对于简单系统而言)，往往用于瀑布模型。
  • 使用者，软件工程师

• 详细设计文档

  • 印度的详细设计文档。
  • 详细设计文档的维护
  • 不需要写，千万不要写详细设计(结对编程时)。
  • 详细设计和代码是一种重复，直接看代码，看 log。
  • 就系统里的重点，难点，复杂算法等写详细设计，类图，顺序图， 活动图，状态图，不需要描述每一个类，每一个方法。
  • 即便写了，也别花费力气去维护，用过就丢弃。
  • 往往用于瀑布模型

• 必要/重要程度排序

  • 需求文档，测试用例和用户手册，长期维护，及时更新
  • 架构设计文档，长期维护，适当更新
  • 概要设计文档，可以不维护，不更新
  • 接口设计和详细设计，不维护，不更新
  • 可行性研宄报告，极少会写

2 文档使用的权衡

• 规范统一的文档模板，罗列出文档可能需要的方方面面，不仅给出标题，还有说明，特定领域的相应条目。推荐，但不强制。缺点，重复，难以发现差异

• 混杂文档，可能包含需求，设计，代码，测试用例等所有相关的内容，格式不限，内容不限，草图，会议纪要/结论。缺点，可能会遗漏一些东西，但专业的开发人员和强有力的沟通能帮助我们不遗漏有用的东西。使用者，软件开发人员。

• 文档格式

  • 内部使用的设计文档，实用主义，格式随意，在白板和纸上画的草图和文字描述可以拍下来直接插到文档。
  • 面向客户的用户手册，正式，规范，美观。
  • 软件的编码 高于 详尽的文档，

• 文档多少

  • 瀑布模型，文档可以多一些，敏捷/增量/迭代模型，文档可以少一些；
  • 多站点开发文档需要多一些，单站点开发，文档可以少一些， •开源软件最好有较为完备的文档(架构设计文档/使用说明书)， •大型复杂系统，文档可以多一些，小型简单系统文档可以少一些 •强有力的沟通可以减少文档的使用

• 增量和迭代，

  • 增量，每个增量是个小瀑布
  • 迭代，每个迭代周期里，需求，设计，编码和测试同步进行。

• 尽量降低文档的维护成本，概要/详细设计文档不用维护

• 有些文档可以不写，概要/详细/接口文档，(只对难点，重点的地方做设计)；

• 唯一必须的文档是需求文档或测试用例(二选一)需求文档和测试用例是重复的。验收测试用例(需求文档)，单元测试用例(设计文档)

• 只有需求文档，包含用例分析和会议纪要，对于小型系统可以工作。

• 太多的文档增加软件的维护成本

• 指导原则，实用主义，实事求是，具体问题具体分析

3 图

• 图往往具有极强的表现力，一图顶千言，可以增加软件的可理解性， 广泛应用于各种文档，例如软硬件架构图
• 功能，记录信息，沟通工具，帮助理清思路
• RUP + UML
• 具体使用什么图，具体问题具体分析，UML 或普通的框图(架构图) 均可。
• 不要深入细节，香则表现力急剧下降，图中元素 7+-2，天然适合表现 high level /概要性的信息，细节的东西用代码来表达。
• 表现复杂问题需要分层，自顶向下逐层风解，硬件结构图。