软件设计文档编写概述

软件设计的三种模型：

瀑布式、快速原型法以及迭代式
自从1968年提出“软件工程”概念以来，软件开发领域对于借鉴传统工程的原则、方法，以提高质量、降低成本的探索就从未停止过。而在这个过程中，提出了许多不同的软件开发模型，典型的有：瀑布式，快速原型法以及迭代式开发。

瀑布式模型

是由W.W.Royce在1970年最初提出的软件开发模型，在瀑布模型中，开发被认为是按照需求分析，设计，实现，测试 (确认)， 集成和维护的顺序的进行。

快速原型法

快速原型模型的第一步是建造快速原型，实现客户或未来的用户与系统的交互，用户或客户对原型进行评价，进一步细化待开发软件的需求。通过逐步调整原型使其满足客户的要求，开发人员可以确定客户的真正需求是什么；第二步则在第一步的基础上开发客户满意的软件产品。

迭代式开发

在迭代式开发方法中，整个开发工作被组织为一系列的短小的、固定长度（如2周）的小项目，被称为一系列的迭代。每一次迭代都包括了需求分析、设计、实现与测试。采用这种方法，开发工作可以在需求被完整地确定之前启动，并在一次迭代中完成系统的一部分功能或业务逻辑的开发工作。再通过客户的反馈来细化需求，并开始新一轮的迭代。

不同的开发模型，对于设计阶段的工作要求也不尽相同。相对来说，瀑布式模型中对于设计文档的粒度要求得最细，而快速原型法对于设计要求比较弱，迭代式开发在每一阶段中的设计文档工作量都相对较少，但在软件开发完成后，最终的设计文档完善程度要比快速原型法的好。

软件设计总体思路

软件设计的本质就是针对软件的需求，建立模型，通过将模型映射为软件，来解决实际问题。因此软件设计需要解决的核心问题是建立合适的模型，使得能够开发出满足用户需求的软件产品，并具有以下特性：

• 灵活性（Flexibility）
• 有效性（Efficiency）
• 可靠性（Reliability）
• 可理解性（Understandability）
• 维护性（Maintainability）
• 重用性（Reuse-ability）
• 适应性（Adaptability）
• 可移植性（Portability）
• 可追踪性（Traceability）
• 互操作性（Interoperability）

因此，软件设计并没有一套放之四海而皆准的方法和模板，需要我们的设计开发人员在软件的设计开发过程中针对软件项目的特点进行沟通和协调，整理出对软件项目团队的行之有效的方式，进行软件的设计。并保障软件设计文档的一致性，完整性和可理解性。

谁来进行软件设计

在我们开发人员中，有很多人这样理解：“软件设计文档就是软件架构师和设计人员的事情”，其实不然。设计文档是整个软件开发团队的产出，其中有些设计文档由架构师或者设计人员给出，有些文档由开发人员给出。这并没有一定的区分。

最佳实践

我们经常听到这样的话：

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

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

设计文档分类与使用

通常来说，作为软件项目，我们需要有这几类文档

• 需求说明文档
• 功能设计文档
• 系统架构说明书
• 模块概要设计文档
• 模块详细设计文档

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

软件设计文档是我们在软件设计开发过程中形成的，用来在软件设计开发团队内部以及与各干系人之间进行沟通的文档，记录了软件项目中的各种知识，方案的思路、以及各种决策意见。

下面我们就软件设计开发过程中必须要完成的工作进行梳理，而我们需要注意到，这些需要完成的工作，在不同的开发流程模型的指导下可能有不同的时间要求，而我们需要关注的是在这个阶段内需要完成的工作，以及这个阶段内我们需要沟通的人员。

需求分析

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

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

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

功能设计

功能设计与需求分析差不多同时在开展，在很多软件项目中，对于功能设计不是特别重视。
但对于某些软件项目而言，这是一个相当重要的工作。
1.对于主要是用户界面的软件项目来说，功能设计可以看作是画出原型界面，描述使用场景，获得用户认可的过程。
2.对于没有界面的软件项目来说，则功能设计与需求分析的区分比较模糊。
参与的人员与需求分析的参与人员类似，架构师更侧重于参与此类工作，并给与一些实现层面的判断和取舍。
功能设计需要明确的核心是 系统的行为

系统架构设计

系统架构设计是一个非常依赖于经验的设计过程。需要根据软件项目的特定功能需求和非功能性需求进行取舍，最终获得一个满足各方要求的系统架构。系统架构的不同，将很大程度上决定系统开发和维护是否能够较为容易的适应需求变化，以及适应业务规模扩张。
架构设计工作中，用户参与程度很低。软件开发团队中的需求人员参与程度很低，但团队中的所有核心设计和开发人员都应该参与其中，并达成一致意见。
架构设计的主要成果，是将系统的不同视图予以呈现，并使之落实到开发中：

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

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

模块/子系统概要设计

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

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

模块详细设计

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

总结

软件设计文档作为软件开发团队的沟通、理解、知识共享的手段，具有非常重要的意义。
而根据软件团队的规模，对于文档上承载的信息详细程度可以有不同程度的要求。

软件团队对于如何使用设计文档有统一的理解，并坚持更新设计文档，才是软件设计的最佳实践！

附录：

软件设计所需要的知识与技能

• UML 统一建模语言
• 软件工程
• 面向对象的编程 OOP
• 操作系统
• 数据库原理
• 设计模式
• 沟通能力