如何写应用软件设计文档

如何写应用软件设计文档1 引言自IT系统诞生至今，如何沟通需求的方法讲了不少，如何设计软件的方法讲了不少，如何开发讲了不少，现在也开始逐步的讲测试了，但是唯独没有人系统的讲如何写设计文档，尤其是指派不擅长写文档的开发人员完成文档时，这项工作就成了一项让他们“头疼”的活。谁都知道文档重要，说起别人的文档头头是道，等到落笔的时候又不知道从哪里下手，在哪里收笔，而且经常出现的文档问题如：l 不伦不类型：n 概要设计写的像系统功能需求n 概要设计介入了详细设计的范畴n 概要设计像是程序速查手册l 态度不良型：n 觉得没什么可写的，都是大家知道的事n 纯粹就是应付检查l 上述几点都是在设计文档中经常出现的毛病，还有其他毛病，比如逻辑性不严密，缺乏层次性等等，就不一一列举了。诚然，写设计文档的方法和手段很多，尽管软件开发技术多变，软件需求多变，但是我们应当尽量的固化设计文档的结构、写法和思考路线。如同音乐多变化，但是表达音乐的五线谱是固定的。1.1 预期读者1、 设计人员：设计应用系统的设计师。2、 开发人员：开发应用系统的工程师。2 设计文档的现状根据我国软件行业项目开发型企业的现状，设计文档只能发挥如下效果：l 协助梳理设计师思路l 过评审l 让新来的开发人员初步熟悉系统l 验收的时候用。发挥完上述作用后，几十页到上百页的设计文档就逐步束之高阁。和咱们软件工程教科书上说的差别很大是吧。其实造成这种现状的原因非常多，部分原因列举如下：l 团队的管理问题；l 领导层重视程度问题；l 不会写设计文档的问题。本文主要通过提高书写设计文档能力来改善设计文档使用效率和效果。3 为什么要有设计文档1、 承上启下：将需求转换为实现的中间步骤，将软件系统需求转换为未来IT系统的过程；2、 新人介入的桥梁：新来的设计师或者开发人员除了了解相关需求外，阅读设计文档是他们进入角色的最高效的步骤。这时候的设计文档起着引路人的作用；3、 共同工作的规范：代码体系、接口规约、命名规则。这是项目小组今后共同作战的基础，有了开发规范和程序模块之间和项目成员彼此之间的接口规则、方式方法，大家就有了共同的工作语言、共同的工作平台，使整个软件开发工作可以协调有序地进行；4、 运维和后续开发的图纸：对后续的实施、维护工作起到关键性的影响。设计本身有优劣，设计文档作为一面镜子如实的反映设计思想，但是设计文档不应当成为一个非标准化，高个性化的“手艺”而存在。4 设计文档书写原则1、 明确使用对象：不清楚谁将会使用该文档直接导致文档质量的低劣。给婴儿吃饭用成人的大勺，即便镶着黄金，可行吗？2、 设计在精而不在多：思路清晰，字数自然不在话下。况且字数太多的文档也没人看。3、 具备文字功底：文字表达能力是一个成熟的设计师必备的基本功，语言这个东西是要练习的。大部分技术人员沉浸在技术海洋中，往往忽略了文字功夫。5 设计阶段的工作无论采用何种分析技术、分析手段，系统模块分解合并思想都是通用的。根据工作性质和内容的不同，软件设计分为概要设计和详细设计。5.1 概要设计阶段把软件按照一定的原则分解为模块层次，赋予每个模块一定的任务，并确定模块间调用关系和接口。 在这个阶段，设计者会大致考虑并照顾模块的内部实现，但不过多纠结于此。该阶段工作主要集中于：l 划分模块、分配任务、定义调用关系。l 模块间的接口与参数传递在这个阶段要定得十分细致明确，l 应编写严谨的数据字典，避免后续设计产生不解或误解。概要设计一般不是一次就能做到位，而是反复地进行结构调整。典型的调整是合并功能重复的模块，或者进一步分解出可以复用的模块。在概要设计阶段，应最大限度地提取可以重用的模块，建立合理的结构体系。概要设计文档最重要的部分是分层结构图、数据流图、数据字典以及相应的文字说明等。以概要设计文档为依据，各个模块的详细设计就可以并行展开了。现在大部分项目采用面向对象的分析、设计方法。总的来说面向对象的分析方法和结构化模块分析的方法并不矛盾，第一步都是进行模块的合并及分解，然后划分包结构、类及对象间的关系、类的对外属性、方法及协作。在一个模块下的类、类属性、方法的内部实现可以作为详细设计内容。一个模块的基类当然放到这个模块去写，如果几个模块均使用一个基类或实现一个接口，那就分解出一个公用模块，在那个公用模块写这些共同引用的内容，这个和模块分解同样不矛盾。5.2 详细设计阶段依据概要设计阶段的分解，设计每个模块内的算法、流程等。在这个阶段，各个模块可以分给不同的人去并行设计。在详细设计阶段，设计者的工作对象是一个模块，根据概要设计赋予的局部任务和对外接口，设计并表达出模块的算法、流程、状态转换等内容。详细设计文档最重要的部分是模块的流程图、状态图、局部变量及相应的文字说明等。一个模块一篇详细设计文档。这里要注意，如果发现有结构调整（如分解出子模块等）的必要，必须返回到概要设计阶段，将调整反应到概要设计文档中，而不能就地解决，不打招呼，在目前的技术条件限制下，只能用管理手段进行约束。5.3 模块化分解及合并方法不管是面向过程时代还是面向对象时代，甚至是SOA时代，分层逐级进行模块的分解都是必不可少的过程。一般所使用的方法是：按照需求，将软件逐级细化，分解为不必再分解的模块，然后合并相同功能的模块，每个模块完成一个或多个功能，为一个或多个父模块服务（即接受调用），也接受一个或多个子模块的服务（即调用子模块）。6 概要设计和详细设计的区分与联系6.1 概要设计和详细设计的区分概要设计文档相当于机械设计中的装配图，而详细设计文档相当于机械设计中的零件图。概要设计实现软件的总体设计、模块划分、用户界面设计、数据库设计等等， 详细设计则根据概要设计所做的模块划分，实现各模块的算法设计，实现用户界面设计、数据结构设计的细化，等等。 概要设计里的功能应该是着重于功能描述，对需求的解释和整合，整体划分功能模块，并对各功能模块进行详细的图文描述，应该让读者大致了解系统作完后大体的结构和操作模式。详细设计则是重点在描述系统的实现方式，各模块详细说明实现功能所需的类及具体的方法函数，包括涉及到的sql语句等。概要设计里面的数据库设计应该重点在描述数据关系上，说明数据的来龙去脉，在这里应该结合我们的一下结果数据，说明这些结果数据的源点，我们这样设计的目的和原因。详细设计里的数据库设计就应该是一份完善的数据结构文档，就是一个包括类型、命名、精度、字段说明、表说明等内容的数据字典。6.2 概要设计和详细设计的联系概要设计是详细设计的基础，必须在详细设计之前完成，包括系统的总体设计文档、以及各个模块的概要设计文档。每个模块的设计文档都应该独立成册（或章）。概要设计经复查确认后才可以开始详细设计。详细设计必须遵循概要设计来进行。详细设计方案的更改，不得影响到概要设计方案；如果需要更改概要设计，必须经过项目经理的同意。详细设计，应该完成详细设计文档，主要是模块的详细设计方案说明，每个模块的详细设计文档都应该独立成册。概要设计和详细设计是交叉重叠进行的，不是说概要设计阶段就一点不考虑具体实现，详细设计阶段就机械执行概要设计思路。7 概要设计文档的组成概要设计文档由以下章节组成：引言：目标、范围、术语表、参考资料；总体设计：总体描述、约束、设计原则、总体结构与模块、功能与模块的关系、规模与性能评估；模块设计： 设计简述：每个模块“做什么”、简要说明“怎么做”（输入、输出、处理逻辑、与其它模块的接口，与其它系统或硬件的接口），处在什么逻辑位置、物理位置；接口设计：总体说明外部用户、软、硬件接口；内部模块间接口（注：接口系统界面）对象模型：提供整个模块的对象模型，如果模型过大，按照可行的标准把它划分成小块，所有对象之间的关联必须被确定，每个图必须附有简单的说明。运行设计：运行模块组合、控制、时间；描述系统如何响应各种事件。一般使用顺序图和状态图。确定不同的场景（Scenario）是第一步，不需要确定所有可能的场景，但是必须至少要覆盖典型的系统用例，然后使用顺序图表示。确定系统中一些重要的对象并为之提供状态图。 数据结构：逻辑结构、物理结构，与程序结构的关系，数据状态汇总说明； 配置设计：业务发生有限的变化时（每个业务模块本身的业务逻辑没有变的情况下），就能够比较方便地修改系统程序模块间的调用关系而实现新的需求。如果这种调用关系被设计成存储在系统配置体系下，如数据字典里，则会极大的提高系统的灵活度。 出错设计：出错信息、处错处理； 其他设计：保密、维护；进程设计：部署设计：数据库设计：安全设计逻辑结构设计物理结构设计附录：数据字典清单业务表单中的选项状态规定业务类型8