[转帖]粗看日本软件设计文档

转载说明：
本文是从公司内部技术支持论坛看得，作者不详。

作为对日开发的一员，应该多学习日方的长处，比如说文档。

=========================================================================

今天有幸拿到一份同行兄弟给我的对日外包软件设计文档，很平常的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元素作了捆绑指定，看了整个设计就通畅了。


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

今天的发文不代表任何含义，希望国内IT同仁们继续努力！