现代软件工程讲义 7 设计阶段 Spec
在前一个博客里 (典型用户), 我们讲了怎么收集, 分析和验证用户的需求。 这里我们讲 spec – specification
Specification, 又叫spec, 有两种:
a) functional spec, 软件功能说明书, 主要用来说明软件的外部功能, 和用户的交互情况 (把软件当作一个黑盒子)
b) technical spec, 软件技术说明书, 又叫 design doc, 设计文档, 主要用来说明软件内部的设计 (把软件当作一个透明的箱子)
有同学说, 我们崇尚动手, code & fix 就是我们的座右铭, 写那么多文字作甚? 上次来了个需求, 我一看图纸, 很简单, 不就是做个烟囱么? 干!
做到一半, 用户来了把我打了一顿!
我冤枉啊
图纸拿倒了, 原来是要挖一口井!
后来我只好强力 "重构", 把烟囱强力插入地里去, 累坏了…
笑话讲完了，我们继续讲 functional spec: 从用户的角度描述软件产品的功能, 输入，输出，界面, 功能的边界问题, 功能的效率问题(对用户而言), 国际化, 本地化异常情况, 等; 不涉及软件内部的实现细节
谁来写spec? 项目的PM, 或者其他人员
谁来实现spec? 开发人员, UX/UI 设计人员
谁来验证spec? 质量保障人员 (QA)
怎么写好spec? 其实就是一件事情描述清楚, 下面是一个练习:
如果你要给一个外星人描述怎么系鞋带, 写一个 “系鞋带“ 的spec （用英语）, 你怎么写?
第一, 我们要定义好相关的概念
—what is “shoe”, “shoe laces”, “tied shoe laces”, and “untied shoe laces” 鞋, 鞋带, 系鞋带, 解鞋带都是什么概念
—Benefit of this feature “tie your shoe laces”。 系好鞋带的好处是什么
—The goal of the feature? 系鞋带的目标是什么?
—What does “success” look like? 什么叫系好了?
—Unambiguous steps to achieve from “untied” to “tied” 明确的步骤来演示系鞋带的过程
第二, 规范好一些假设 （assumptions）, 例如, 鞋带是已经穿好在鞋上的么? 什么样的鞋属于我们要处理的?
第三, 避免一些误解， 下面这个从技术上也是 ”鞋带绑紧了“, 但它是 “系好了”么? 打了死结算成功么? 要打多少个蝴蝶结才算好?
第四, 厘清一些边界条件, 下面的情况属于好的系鞋带状态呢, 还是不好的状态呢？ 这需要PM/Dev/Test 协商达成一致意见。鞋带要打多紧才算好? 打好的鞋带能拖在地上么?
第五, 描述主流的用户/软件交互步骤。
第六, 一些好的功能还有副作用, 我们要把这些副作用明明白白地写出来。
例如: 美国很多地区用节能灯(LED) 代替了原来的白炽灯, 但是LED 灯泡发热少, 下雪天不能融化灯面的积雪, 导致交通问题。当初的spec 要把这一副作用 (危险) 给写出来。
有人说， 我们敏捷的团队，就喜欢直接的面对面的交流，不喜欢搞文档什么的，多好！
其实大多数情况下，留下文字的文档是很有好处的，相对于后来的浪费，当初花的时间真的是太值了。 看下面的例子:
自习课时，教务主任走进来，告诉班长“帮我找两个人，我要班花”, 同时两手在胸前做了一个抱花的动作, 就走了. 班长就组织全班投票评选起班花来，闹了一节课，搞了一些大数据, 终于统一了意见，选出了班里最PL的两mm。于是两mm很羞涩的去找主任，主任说：“怎么是你们? 男生都哪去了? 好吧, 跟我去后勤，我要搬花。。。”
当面, 直接的交流当然很敏捷, 但是还是要留下文档, 以明确用户的需求。
在大规模软件的开发中， 我们一定要说清楚服务质量是什么等级, 意味着什么，不然就会人云亦云，以谬传缪。例如: 三峡大坝到底能防多大的洪水?
我们看一看从 2003 年到 2010 年 大家的理解:
人民群众看不见具体的spec, 只能道听途说，专家有细致的解释: http://news.163.com/10/0722/01/6C5MUM6R00014AED.html
写好的 spec 的秘诀不多, 只有下面三条:
实践, 实践, 再实践
spec 的最大敌人是什么? 乏味。软件公司的大部分人都不喜欢读文档，更不要说大学生了。 强迫大学生写乏味和没有人读的文档，简直就是扼杀同学们对软件工程的兴趣。 怎么把spec 写让人读了不困？
- 用活生生的人物和故事描述用户怎样用软件的 (参见上文 典型用户 )
- KISS - 保持简单, 直接的描述。涉及UI 的部分可以直接上图。 也可以画表格，不要写长篇累牍的文字。
- 如果是技术文档，最好把示例代码写上，单元测试也写好，让程序保证spec 的正确性，也让读者可以验证 spec 的正确性。
- 把边界条件规定清楚，理工科思维的工程师们看到这里大脑就兴奋起来了 - 他们想找出你 spec 的破绽!
spec 的另一个敌人是时间。 几乎在spec 写好的那一瞬间，spec 就开始过时了。 容颜易老，spec 尤甚，怎么办?
- 记录版本修订的时间和负责人 - 这样出了问题好去找人。
- 在spec 中要说明如何验证关于功能的描述，从spec 的描述中就能知道单元测试怎么写， 最好把测试用例也链接上。
- 把spec 和测试用例，项目任务等放一起 (例如 TFS 上面)，相互链接。
- 变化一定会发生的，与其在 spec 中有意忽略这一点，不如主动挑明哪些部分是容易发生变化的，提前做好预案。 哪些部分如果改变，会有何种连锁反应。
- 在做任何改动的时候，一定事先参考spec，事后更新spec, 团队领导人不应该在没有spec 的情况下做拍脑袋的决定。
有spec 的模板么? 很多同学问，似乎很多同学有这样的希望，一旦搞到某文档的模板， 某课程的PPT，事情就成功了一大半。 盲目地套用最最给力的模板，对项目有大的副作用。 各位PM 要注意。 把上面正反的例子综合起来，就是一个模板:
- spec 的目标是什么，spec 的目标不包括什么
- spec 的用户和典型场景是什么
- spec 用到哪些术语，他们的定义是什么
- 用户如何使用软件的功能的
- 各种边界条件是什么，软件功能应该怎么样变化
- 这些边界条件多了去了，用户数量的变化，输入内容的上限下限， 不同国家/地区/文化/语言/硬件/软件版本/环境参数….
- 功能有什么副作用，对于其它功能有什么显性或隐形的依赖关系?
- 什么叫“好”, 什么叫这个功能测试完了，可以交付了?
