软件设计文档如何编写，设计文档内容都包括什么

我们经常听到这样的话：

“设计文档没有用，是用来糊弄客户和管理层的文档”；
“用来写设计文档的时间，项目开发早就做完了”；
“项目紧张，没有时间做设计”；

这些言论，并不是正确的观念，根据项目的实际情况，开发设计团队可以约定设计文档的详细程度。
项目团队需要保障设计文档的完整性和一致性，在项目进度紧张的情况下，软件设计文档可以更初略一些；
在项目时间充裕的情况下，相关文档可以更为详尽。但是在项目开发过程中，需要软件设计开发团队对于设计文档有共同的理解。有利于程序的设计工作，以及对程序的修改和维护工作。

设计文档的分类与作用
通常来说，作为软件项目，我们需要有这几类文档

1，需求说明文档。
2，功能设计文档。
3，系统架构说明书。
4，模块概要设计文档。
5，模块详细设计文档。

一般说来，需求分析属于软件定义方面 ；
而概要设计（功能涉及，系统架构）、详细设计（模块概要，模块详细）属于软件开发的阶段 ；

就像之前说到的，在软件团队中，对于以上的文档的要求是可以完全不同的，在简单项目中，可能所有类型的文档放在一个文档中进行说明；在复杂项目中，每一类文档可能都要写几个文档；而在最极端的情况下，可能每一类文档都能装订成几册。因此，在我们软件设计和开发人员心目中需要明确的是：文档并不是我们进行设计的目标，也不是我们设计过程中额外的工作。

软件设计文档是我们在软件设计开发过程中形成的，用来在软件设计开发团队内部以及与各干系人之间进行沟通的文档，这些文档记录了软件项目中的各种知识，方案的思路、以及各种决策意见。
下面我们就软件设计开发过程中必须要完成的工作进行梳理，而我们需要注意到，这些需要完成的工作，在不同的开发流程模型的指导下可能有不同的时间要求，而我们需要关注的是在这个阶段内需要完成的工作，以及这个阶段内我们需要沟通的人员。

需求分析
需求分析是我们进行任何一个软件项目设计开发过程中都必须要完成的工作。

这个工作通常与客户一起完成。在不同的项目中，这个“客户”可能来自真正的购买产品的用户，使用系统的用户，也有可能来自团队的某个人员，如产品经理等。软件设计开发团队的参与成员根据项目的不同规模，则参与的人员也有所不同。原则上，设计开发人员参与的时间点越早，对于需求的理解和把握会更好。这个阶段，通常需要软件架构师参与其中。从资源优化的角度来说，开发人员不必参与需求分析，但需要理解需求。

需求分析的结果通常我们需要使用需求说明文档来描述，目前主流的需求描述方法包括：用户例图。这些方式有所不同的侧重，其核心思想就是描述清楚用户的使用场景。但无论采取何种方式，进行需求的描述，需求说明需要明确以下几点：

• 所需要开发的软件系统边界
• 系统所有的相关及使用人员角色
• 系统关键的使用场景
• 系统规模、性能要求以及部署方式等非功能性需求

功能设计
功能设计与需求分析差不多同时在开展，在很多软件项目中，对于功能设计不是特别重视。但对于某些软件项目而言，这是一个相当重要的工作。对于主要是用户界面的软件项目来说，功能设计可以看作是画出原型界面，描述使用场景，获得用户认可的过程。而对于没有界面的软件项目来说，则功能设计与需求分析的区分更为模糊。

参与的人员与需求分析的参与人员类似，架构师更侧重于参与此类工作，并给与一些实现层面的判断和取舍。

功能设计需要明确的核心是：

• 系统的行为

系统架构设计
系统架构设计是一个非常依赖于经验的设计过程。需要根据软件项目的特定功能需求和非功能性需求进行取舍，最终获得一个满足各方要求的系统架构。系统架构的不同，将很大程度上决定系统开发和维护是否能够较为容易的适应需求变化，以及适应业务规模扩张。

架构设计工作中，用户参与程度很低。软件开发团队中的需求人员参与程度很低，但团队中的所有核心设计和开发人员都应该参与其中，并达成一致意见。

架构设计的主要成果，是将系统的不同视图予以呈现，并使之落实到开发中：

• 系统开发视图及技术路线选择
• 系统逻辑视图
• 系统部署视图
• 系统模块视图
• 系统的领域模型

在软件开发过程中，系统的架构不是一成不变的，随着设计人员和开发人员对于系统的理解不断深入，系统的架构也会发生演化。在软件项目中，架构设计是开发团队沟通的统一语言，设计文档必须要随着系统的变化进行更新，保障开发团队对于系统的理解和沟通的一致性。

模块/子系统概要设计
模块/子系统的概要设计，由架构师参与，核心设计和开发人员负责的方式进行。
在概要设计工作中，我们需要在架构确定的开发路线的指导下，完成模块功能实现的关键设计工作。在概要设计阶段，需要关注于模块的核心功能和难点进行设计。这个过程中更多推荐的采用UML来进行概要设计，需要进行：

• 模块实现机制设计
• 模块接口设计
• 关键类设计
• 画出时序图
• 交互图等。

模块详细设计
在瀑布式开发模型中，模块的详细设计会要求比较严格，将所有类进行详细设计。据我所知，除了一些对于系统健壮性要求非常严格的软件项目，如国防项目，金融项目还要求有详细设计文档之外。其他的项目大多采用其他方式来处理这样的工作，如自动化测试等。

综上所述，软件设计文档作为软件开发团队的沟通、理解、知识共享的手段，具有非常重要的意义。而根据软件团队的规模，对于文档上承载的信息详细程度可以有不同程度的要求。我们软件团队对于如何使用设计文档有一个统一的理解，并坚持更新设计文档，这就是软件设计的最佳实践！