工程管理文档:概要设计说明书

2019-11-05

  软件工程管理中,有几个比较重要的文档,软件开发者这边会接触到的,有:需求输入表、需求规格说明书,概要设计,详细设计,自测报告。这里我想要谈一谈概要设计文档,也是对于开发者而言,最重要的文档。其他文档及相关过程,另写文章总结。

一、谁负责?
  谁负责这个问题一定要明确?我觉得这个问题很重要,非常重要。有些时候,项目的技术负责人会把概要设计交给属下每一个人负责一部分,然后收集并综合起来。我认为,这是不对的。一般来说,一个技术团队,技术leader 就是那个技术最厉害的人。概要设计文档应该由技术leader完全负责。如果是web或者mobileApp项目,可能开发团队不超过二十人,分成两三个、三四个小组,而且,大家的技术技能还比较类似。如果是算法软硬件结合项目,或CAD类型项目,可能涉及到三四十人,技能领域可能差别较大,一个小组的内容,其他的小组可能完全不会,或者花两年的时间学习也能够会。这就比较麻烦了。如我们之前的项目:虚拟制衣CAD项目:CAD组、渲染算法组、物理引擎组。这样子的项目,每个方向的难度较大,就需要小组长来辅助技术负责人做好概要设计。技术负责人不能把这些工作下放给普通开发者。我一向秉承拿最大份的酬劳,输出最大的价值,担最大份责任的原则。
   为什么一定要技术负责人来做概要设计呢?找组员A过来,他是不是也能干了这个活儿呢?比如说,他手上拿着Scrum或者UML的教材,是不是也能照猫画虎呢?并不能,软件工程,与其他类型项目的工程也有类似之处,技术积累的年限是保证经验的简单的标准。经过长年的训练,一个领导人对于项目的各个环节都非常熟悉,虽然未必有每个环节的负责人熟悉,但是对于项目的把控肯定是行业经验所带来的较优水平。

二、有什么作用?
  概要设计说明书是给开发团队使用的。对于小型项目,概要设计说明书可能不不重要,可有可无,代码中的注释即足够。对于中大型项目,由于开发周期长,人员变动多,靠口口相传是不够的。规范的、统一的概要设计文档才是保证代码实现 正确的最大保证。软件工程实践里,我们对于术语的使用其实不是那么严谨的,对于组员沟通来讲,会带来一些歧义,所以,我们需要文档以及规范化流程来保证交流的顺畅。

三、要做什么? 什么内容?
  简单来说,就是指导每一个开发者如何开发项目。选择每个模块的实现方案,例如网络功能的模块,是选择基于libevent、libuv等等,还是自己实现,UI框架选择哪个,MVC模式应该如何实现,数据库选择。其二,模块之间的关系,通信方式,例如,有的人喜欢通过构建好model之后,喜欢通过id或者handle的方式在view、controller层使用,有人喜欢完全隔离的View/Controller端,在桌面端项目中模仿Web端的View/Controller层次,有人喜欢在桌面端软件采用前后端分离的方案,有的人不喜欢,既然是技术负责人做了最终的方案选择,就需要为自己的选择负起责任。因为技术方案的选择而代码的开发周期增加,不能把过错转移到普通组员身上。若选择合适的方案让预估开发周期变短,那是设计者的功劳。

百科对概要设计的定义为:

在该阶段,根据上一阶段的需求来确定总体的实现方案,确定整个软件的大体布局,各模块的功能以及模块之间的衔接,模块与外部系统的关系。在这个阶段,设计者会大致考虑并照顾模块的内部实现,但不过多纠缠于此。主要集中于划分模块、分配任务、定义调用关系。模块间的接口与传参在这个阶段要定得十分细致明确,应编写严谨的数据字典,避免后续设计产生不解或误解。概要设计一般不是一次就能做到位,而是反复地进行结构调整。典型的调整是合并功能重复的模块,或者进一步分解出可以复用的模块。在概要设计阶段,应最大限度地提取可以重用的模块,建立合理的结构体系,节省后续环节的工作量。

概要设计文档最重要的部分是 分层数据流图结构图、数据字典以及相应的文字说明等。以概要设计文档为依据,各个模块的详细设计就可以并行展开了。

    有的项目涉及到硬件部分,我们需要把视野放的更开一些,若硬件部分的工作不多,也需要把它囊括在内。所谓设计文档,是针对于整体过程而言,非仅软件代码部分。

在整个过程中,我们需要做如下图表绘制:
1,用例图
  用例图(user case) 应该在需求分析阶段绘制,落实到详细设计文档中。概要设计阶段,设计者应该熟悉了每一个用例,并细化至 活动图。
2、组件图(component diagram组件是封装了可执行特定功能的单位。 组件的类型包括了可执行文件、文档、数据库表格、文件和库文件等。一些开发者,把lib当作组件。其目标是软件就像垒积木一样,垒组件就能形成新的软件。然而,UML中组件的含义更加宽泛,这里会导致歧义,提一句。
3、class diagram
  class diagram基本上是在 详细设计阶段 绘制的。没有详细设计的工作,如何能够做好class 层次,而且,在具体实现的时候,会发现,设计会做更改。若不打算写详细设计文档,可以绘制关键模块的class diagram。

4、模块关系图
  概要设计过程,需要确定开发过程所用的过程方法(开发模型)。如XP、Scrum、瀑布等。从开始文档制作始,就定好了,且在执行了。如想要走瀑布模型,那么制作文档的过程就是独立的,连续一致的;如想要做敏捷过程的,可能概要设计完成了,就开始了编码,同步完善详细设计。

四、如何写?
   我们需要找一份模板,认真的把每个步骤完成。对于文档的格式,其实没必要那么关注。大公司内部早就制作好适合自己的文档格式,中小公司在还没有形成自己的文档时,从互联网上找一些模板,综合一下就可以形成自己所需的格式。经过一两年的迭代,整个团队就会适应这个文档的流程。照猫画虎的填写完当然是不难的,难的是做出合理的设计。写出文档与写好文档是两回事。这里直接牵扯出了另外一个问题:如何评价?这个问题重要性不言而喻,谁有能力去评价一个技术负责人是否能力合格呢?到底如何去评估呢?我的评价标准很简单:在2.0的版本中,不会有组员强烈提出架构代码的重构。
  概要分析是迭代着做的,不是花一周、两周做好了,不修改了,成为标准、规范了,如同”C++代码规范“。它会在我们进行详细设计的过程中反复被修改。软件工程中,建议设计阶段占时间1/4,设计者在足够长的时间内,应该把绝大多数难题都解决掉。但是,我们又不能无限期修改下去,需要明确时间点。所以,leader与各组长完成 初步的详细设计之后,进行第一次修改。各组长与组员进行详细设计,较长时间后,组长修改模块设计,与leader 共同确定 第二次 修改。总共三版。在程序开始开发代码之前,应该封存。

  此过程中,大概会提出一些问题:
1,设计中明确需要一个模块,但是,在没有详细设计之前,甚至是没有开发时,我们并不确定,这个模块是否满足预期的性能、功能要求。有可能做出来才能明确,该方案不满足需求,该功能无法实现。
    对于这种问题,真的是毫无办法,因为,已经超出了知识范围。只能请教更高级的专家。
2,为什么我只写了一种方案,并没有多种可选方案?
  因为,已经把可选项排除了。我们可以备选方案也加上,首选方案的某些问题可能未被发现,一旦发现,首选方案可能也变成了备选方案。
3,若在一个老的项目上,重新实现第二版,那么,我们会觉得,概要设计这个过程中,并没有做什么事情,总感觉心里不踏实,怎么办?
   不用担心,本来就是如此,在之前的版本里,需求、概要、详细 分析,都作过。新版本的设计中,只需要继续优化就好了。

P.S. 这篇总结我放了好久哦,躺两年了吧。今年者的是懈怠了。终于把结婚这个任务完成了,也在这个城市安家了,人生正式进入新的阶段。对于做技术的道路,这两年我也有的新的认知,希望能走上不一样的道路吧。
P.P.S. 若需要各种文档模板,可留言。我稍后整理出来整套的模板供下载。

  1. https://en.wikipedia.org/wiki/Systems_development_life_cycle 
  2. https://elf8848.iteye.com/blog/1582323
如果有任何意见,欢迎留言讨论。


[ 主页 ]
COMMENTS
POST A COMMENT

(optional)



(optional)