软件设计文档是我们在软件设计开发过程中形成的,用来在软件设计开发团队内部以及与各干系人之间进行沟通的文档,这些文档记录了软件项目中的各种知识,方案的思路、以及各种决策意见。
通常来说,作为软件项目,我们需要有这几类文档
- 需求说明文档
- 功能设计文档
- 系统架构说明书
- 模块概要设计文档
- 模块详细设计文档
需求说明文档:
用于描述清楚用户的使用场景,最少需要说清楚几点内容:
- 所需要开发的软件系统边界
- 系统所有的相关及使用人员角色
- 系统关键的使用场景
- 系统规模、性能要求以及部署方式等非功能性需求功能设计
功能设计文档:
用于描述系统的行为,与需求分析差不多同时在开展,对于有用户界面的软件项目来说,功能设计可以看作是画出原型界面,描述使用场景。而对于没有界面的软件项目来说,则功能设计与需求分析的区分更为模糊。
此类工作主要由架构师和需求人员一起完成,在此过程中架构师需要在一些实现层面上进行判断和取舍。
系统架构设计文档:
架构设计的主要成果,是将系统的不同视图予以呈现,并使之落实到开发中:
- 系统开发视图及技术路线选择
- 系统逻辑视图
- 系统部署视图
- 系统模块视图
- 系统的领域模型
需要根据软件项目的特定功能需求和非功能性需求进行取舍,最终获得一个满足各方要求的系统架构。系统架构的不同,将很大程度上决定系统开发和维护是否能够较为容易的适应需求变化,以及适应业务规模扩张。此工作中,开发团队中的所有核心设计和开发人员都应该参与其中,并达成一致意见。另外,在软件开发过程中,系统的架构不是一成不变的,随着设计人员和开发人员对于系统的理解不断深入,系统的架构也会发生演化。
架构设计是开发团队沟通的统一语言,设计文档必须要随着系统的变化进行更新,保障开发团队对于系统的理解和沟通的一致性。
模块/子系统概要设计:
模块/子系统的概要设计,核心开发人员需要在架构确定的开发路线的指导下,完成模块功能实现的关键设计工作。在概要设计阶段,需要关注于模块的核心功能和难点进行设计。这个过程中更多推荐的采用UML来进行概要设计,需要进行:
- 模块实现机制设计
- 模块接口设计
- 关键类设计
- 画出时序图
- 交互图等
模块详细设计文档:
详细设计文档的内容包括各个模块的以下内容:
- 算法设计
- 接口设计
- 数据结构设计
- 交互设计等
它在概要设计的高层设计的基础上,从逻辑上实现了每一模块的功能,是编码阶段的主要参考资料,建议在编写过程中粒度不要过细,需要将有关设计的决策考虑进去,包括与其他模块、整体设计的关系、操作的处理流程(包括输入、执行过程、输出、异常处理等),对业务规则的设计考虑等。另外,需要确保页面原型、需求规格说明书所不能反映的设计决策,而开发人员又需要了解的一定要写入详细设计文档中。
软件设计文档并没有一个统一的准则,软件开发设计团队可以约定设计文档的详细程度,但要确保设计文档的完整性和一致性,并且使得软件设计团队和开发团队对于设计文档有一致的理解。