设计文档写些什么才有用？

     一些公司用CMMI做软件开发过程管理，对详细设计过程要求很高，需产出Rose设计模型，画出序列图、活动图等等。本意是为了让Rose设计模型对后续的编码有指导意义。但实际实施过程中发现效果不佳，一是有人不愿意认真写详细设计文档，二是有人不愿意看详细设计文档，问题如下：

 

    1）当详细设计和编码人员实际为同一人时：既然是同一人，自己做事心里有数，整体想清楚了就开始编码，而不愿意写详细设计文档。

    2）当详细设计和编码人员不是同一人时：编码人员根本不愿意看Rose设计模型，一，详细设计要画的很细才有效果，这样一来要读懂别人的序列图、活动图反而不容易；二，如果详细设计做的不够细，那还不如直接看需求文档。

 

    文档有两个功能，一个是指导下游工序进行工作，二是作为档案供将来回忆或新人学习之用；由于上面两个原因，Rose设计模型的第一个功能“指导下游工序进行工作”的功能实际是失效了；而第二个功能呢？在与许多从事软件维护工作的开发人员访谈之后，得到的结论是：大多数人更愿意直接看代码，而不是看详细设计文档（因为设计文档要不就是太粗略，要不就是太细、重点不突出，看不懂）。因此Rose设计文档的第二个功能也失效了。这也验证了前人说的一句话：设计文档是一次性的，或者：代码即文档。

 

    再谈谈设计的目的。设计分为架构设计、概要设计、详细设计。如果说架构设计是规划房子的地基，概要设计则是规划房子的钢筋混凝土框架、详细设计就是规划管道、线路、门窗、外表等等（其中以管道、线路为首要）。对应到软件上，概要设计就是要规划出软件的结构 —— 模块、模块之间的关系、模块内部的类（接口）、类（接口）之间的关系。而详细设计就是规划出软件里的管道、线路，可以认为是贯穿全局的算法。

   

    那么设计文档该怎么写呢？设计文档不是越细越好，写得细了也没人看，稍微发生变化又要去修改。一个合理的设计文档是结构清晰的、重点突出的，也就是概要设计+关键详细设计。概要设计是对软件结构的描述，包括类的责任、接口的责任；关键详细设计，也就是对贯穿全局算法思路的描述。结构的描述，用类图就可以了。而贯穿全局的算法，用序列图活动图可以，用文字描述也行。说清即可，仅此足矣。那么类里面的属性、方法需要在Rose模型里体现吗？这是不必要的，有时间一个个输入到Rose里，不如在IDE里编码来的直接。

 

    设计文档如何使用？首先在设计评审时，供评委评价。其次，对详细设计和编码有限定作用。而详细设计编码最好就是同一个人来做，可省去不必要的文档交流。在编码完成后，设计文档的使命也就完成了。后续没有必要维护设计编码一致性，就算要维护一致性，因为我们的设计文档是只抓重点的，而重点的都是不容易改变的，因此维护一致性的工作量也不大。