竹磬网-邵珠庆の日记 生命只有一次,你可以用它来做些更多伟大的事情–Make the world a little better and easier


113月/1225

日本软件设计文档

发布在 邵珠庆

最近在同兄弟们一起做项目,关注了一下有关日本开发文档的文章跟大家分享一下。

今天有幸拿到一份同行兄弟给我的对日外包软件设计文档,很平常的Excel文档,打开一看内容却感到非常不一般,以前听说过日本IT企业的“认真地死板”,今天算是感受到了。

这份文档分8个sheet,每个sheet明确针对不同描述领域,分别为:链接、版本修正、软件架构和业务物理模型、界面原型、界面原形元素设定 (包含初始化)、界面原形元素数据实现顺序、动作实现顺序、底层数据集描述和实现。怎么说呢?我算是看到过很多设计文档的人了,国内的、欧美的,这次加上 日本的算是全了70%了,我不想对日本发什么感慨,我只是想从这份文档本身出发谈谈看法。

1. 为什么要有独立的链接页面?

其实这个问题我不用多说,但凡是在IT行业做过的都知道这个行业有个很大的特色:早先没什么文档,自从CMM能增加企业光亮开始,文档一夜之间就铺 天盖地的出来了,甚至有段时间国内出现了文档容量攀比态度,各个公司之间,每个IT从业人员之间相互比对谁拥有的文档多,多意味着什么?专业啊!问题是文 档多了管理这些文档也麻烦了,不是丢了就是被某些糊涂蛋删除了,幸好聪明的国人想到了配置管理,我把这些文档分分类放到配置管理库那么就一切OK了。我曾 经入职过一家国内的大公司,第一天上班“师傅”就带给我一个10G的资料让我“学习”,我对这些文档的第一个印象就是支离破碎,看完这个刚有点感觉想看下 面的时候,找不到后面的资料了,当我找到后面资料时思想全乱了,一天下来头昏脑涨,这也是我看到的最讲究逻辑的行业做的最糟糕逻辑的事情了!

所以文档有个链接就非常好了,你可以让每个孤立的文档连成一个整体,让阅读者的思维通畅起来。回过头我重新看了一下RUP2000,里面的文档也是非常讲究相互链接的,不知道为什么这么好的东西到了中国就“消失”了。

2. 版本修正

我觉得国内只要是想正儿八经做IT的都会在各自的文档上加这个,只不过很多人没有考虑一个阅读的科学性,我以前的文档全是在目录后跟版本修正,这样 的话如果一份文档变动非常频繁,那么会造成页面下拉厉害影响视觉。有个细节是,这份日本设计文档的版本修订区是根据每个sheet做修订大项的,每个 sheet的细节分类变更包含其中,这样可以跟踪得很细。我们原来的文档着这方面却可以看出,细心的人写的细,粗心的人写的粗,总之在标准的文档也会有不 标准的地方。

3. 软件架构和业务物理模型

国内也有,至少我以前接触的文档就有这方面的内容,不过大多数是根据欧美风格来的,大框架的描述的非常精美,如果你想看细节架构和数据流就没了。这 份日文设计单独开辟了一个sheet专门描述着描述这件事情,选用的图形比较中规中矩,看了以后至少知道什么是入口,中间经过何等处理,最后的输出是什么 或者什么形式。看来日本并没有大规模推广UML语言,他们就是用了office提供的图形,我现在有些搞不清楚了,国内很多企业标榜自己的设计完全UML 化,出来的文档很专业,结果是少数人看的懂,也许在某些国人眼里,设计就是那天上的月亮岂能让凡夫俗子把玩乎?!

文档的细节是将模型中出现的文字都一一作了解释,有点词汇表的意思,但是没有RUP中词汇表那么大的作用范围。

4. 界面原型

原型这东西最能让阅读者快速理解,2000年开始国内很多IT企业就讲究 快速原型开发方法,但是至今我没看到过一份设计文档带原型,有的是有不过是后期开发完成后补的,这是聪明人做的事情。我看这份文档,到这里我已经完全明白 要做什么了,至少我不会担心我要自己设计什么稀奇古怪的东西。另外这个sheet标注了项目说明,这样结合原型我又能多理解很多东西。说BUG大部分都是 出现在需求和设计阶段,如果你能100%理解你要做什么了,怎么会让BUG穿透这么多层面流到客户地方去?

5. 界面原形元素设定

到这里我作为一个曾经的开发人员就要动手准备做了,本sheet详细描述了整个界面所用到的GUI元素,编程变量名称,类型,长度,格式例子等等, 还有GUI元素的坐标。其实我理解到了开发阶段,基本上就是光做不说的阶段,你还能指望有几个开发需要大量的 激情创造 才能生存下去?所以说,国内的开发吃欧美的编程天才的毒蘑菇吃多了,产生了愉悦的精神幻觉,要知道图灵只有一个他死在美国!

6. 界面原形元素数据实现顺序

这个要详细看看,其实这个sheet我理解的也不是很好,但是从含义来看是对GUI接收和反馈数据作的一个约定,哪些GUI元素是接收数据的,哪些GUI元素是反馈数据的,感觉就是很细节,是对前面一个sheet的补充。

7. 动作实现顺序

国内有个不好的习惯,习惯让测试人员最后写操作手册,我不知道这个是谁发明的并且第一个开始,我只知道这样的人在IT中对IT标准化是个莫大的嘲 笑。这份sheet详细描述了整个界面的操作动作,结合界面元素的不同组合详细写出业务可接收处理过程,如果你要写操作手册,只要结合VBS就可以快速生 成一份XX软件操作手册,何必再劳师动众让本已经疲于奔命的测试人员写呢?

8. 底层数据集描述和实现

这部分详细设计经过GUI收集的数据最终存储问题,国内很多都有这方面的描述,这一块日本作的实际了点,数据名称跟前太GUI元素作了捆绑指定,看了整个设计就通畅了。

最后要说明的是,这只是一份普普通通的日本软件设计文档,设计的内容是一个很小很小的资金查询,这样的东西以前我一天可以做好几个,但是到今天为止我做不出这么详细的设计文档。我觉得现在非常有必要反思一下我的测试用例设计文档 细节决定成败 我不愿意落在口头上。