关于日本软件设计文档的讨论

关于日本软件设计文档的讨论
摘要:
过多的文档就是过度设计吗？CMM5到底是不是我们所需要的？我们又回到了预先设计和渐进迭代的圈子，或许软件设计和XP，Agile的结合点方是我们所寻找的？你的看法又是如何呢？
昨天，conanzero的blog上发了一篇转载的 粗看日本软件设计文档 的日志，日志中提到了：
作为对日开发的一员，应该多学习日方的长处，比如说文档。今天有幸拿到一份同行兄弟给我的对日外包软件设计文档，很平常的Excel文档，打开一看内容却感到非常不一般，以前听说过日本IT企业的“认真地死板”，今天算是感受到了。这份文档分8个sheet，每个sheet明确针对不同描述领域，分别为：链接、版本修正、软件架构和业务物理模型、界面原型、界面原形元素设定（包含初始化）、界面原形元素数据实现顺序、动作实现顺序、底层数据集描述和实现。怎么说呢？我算是看到过很多设计文档的人了，国内的、欧美的，这次加上日本的算是全了70%了，我不想对日本发什么感慨，我只是想从这份文档本身出发谈谈看法。........
而，nmvr2600针对这篇日志发表了 他的不同见解 ，他提到：
想来那个作者是没有在日企或者专门做对日外包的企业工作过的。日本人的文档有时是做得非常的详细。但是我认为他们这么做的初衷却并非像大家通常认为的那样。日本人做事情脑子不习惯转弯，他们的死板有时会让你抓狂。一般外包的项目都会在日本做好设计再拿到中国来。详细的文档（日文叫：仕様書）有时是做得很详细，啥都写上了。这样就可以防止软件在编写过程中发生理解上的错误，但是他们甚至会连你的开发工具版本，安装路径，JDK路径，eclipse要用什么插件都全给在文档里要求上（曾经有一次很变态的经历就是连杀毒软件都给你要求上），有的还给你抓上图，详述安装步骤，让你时不时怀疑到底自己是白痴还是他们是白痴。这样的例子只是一个小的方面。我的感觉是他们的仕様書多数是信不过中国人的智商。......我并没有想说详细的文档不好，只是认为凡事皆有个限度，过度设计是一种错误，过度的文档也是一种错误。不仅浪费时间和精力，而且有时还会带来很多的问题。增加成本不说，过度的文档也可能成为编码的障碍。因为并不是所有的事情都可能在设计时都可以预见到的，当出现问题时为了和文档一致不得不绕个圈子来解决，本来可以有很简单的方法可以搞定的。我是比较推崇XP的人，文档也好UML也好，这些都是为开发服务的，即使是看起来再好的东西，如果它事实上已经给开发带来了障碍了，有什么理由还有继续坚持下去呢。
同时，tcmak也发表了 他的看法，他提到：
更可憐的是現在太多公司盲目地追求什麼 CMM Level 5. 以為有個好看的招牌就會是生意的保證. 可憐是因為這些公司根本不明白什麼是好軟件, CMM Levl 5 有提過什麼是好的軟件嘛? 我不是完全地反對 CMM, (其實很多都是好的 practice, Level 2/3 都有很多好的東西), 但 CMM 也沒有提過如何讓顧客滿意, 什麼沒什麼向顧客方面有關的事情是有提到的. 老實講, 做那麼多的文件出來, 成本是要顧客去付的, 如果對他們沒用的, 或者沒很大用的, 可以不做嗎? 可以做少一點嗎?
过多的文档就是过度设计吗？CMM5到底是不是我们所需要的？我们又回到了预先设计和渐进迭代的圈子，或许软件设计和XP，Agile的结合点方是我们所寻找的？
#9311 评论作者： youway 发表时间：2006-03-19 02:55
只要是把软件当工程来做， 我看文档都十分了得，毕竟下面干活的，都是当作软件蓝领用的，不会把你想得有多聪明，只会发挥他的能力把你想得有多笨。而且设计文档更像是合同的一部分，定义清楚扯皮的事情也少。另外比较中国代工日本软件，印度代工欧美软件，衔接层次和语言文化是不一样的。由于印度软件工厂管理架构成熟，欧美多给到需求这一层，大量的文档是印度公司自己做的，而且他们完成的是设计，实现这两层，在这两层之间，有些东西是他们内部自己可以沟通的，明确的，或是默认的，这样也能减少一定的文档。设计部分也多是由欧美与印度通过沟通共同参与完成的。强调一点，他们不存在来自语言上的障碍。而中国代工与日本的衔接多在设计与实现之间，而且两种操各自母语的人沟通上有先天障碍，再加上都有少说多做的传统文化，所以就造成大家所能看到的日本设计文档。我见过国内有些外包日本项目的公司，干脆就是入门级的程序员，和拉日本项目的老板。日本人也是在用详细文档来规避风险的。日本公司也曾试过把软件外包给印度软件公司来作，他们在需求与设计之间衔接，就因为语言和文化所造成的沟通障碍而放弃，试着在设计与实现之间衔接，造成的情况是浪费印度公司在欧美模式下已经培养起来的软件白领，而且文化的差异较大，即使设计文档详细也能造成不同的理解。日本软件的外包，衔接层次基本就被固定在设计与实现之间，相比较而言，中国是最佳选择。这些年随着日本软件外包在中国的发展，也培养出了一些针对日本项目的软件白领，他们也正尝试或着经历着衔接层次上的转变。还要明确一点，我们看到的日本软件设计文档，是用于外包的，如果他们自己内部实现，未必会有那么罗里罗嗦。ok, 就罗嗦到这。
#9263 评论作者： keyknight23 发表时间：2006-03-17 09:53
操作系统，JDK配置，tomcat版本要完全一致并不是无理要求，有时候某些让你抓耳挠腮水深火热而又感到莫名其妙的问题偏偏就是因为版本差了那么个0.1。日本人文档巨细的目的也就是为了让他们每一个意图组做到最好的落实。所以，我们最好不要误解了他们这样做文档的初衷，并不是为了细而细，而是为了让需求得到最切实的落实。
#9240 评论作者： jerry_yifei 发表时间：2006-03-16 04:37
哈哈，公司是做对日外包的，但是偶不会日语。。。文档（式样书）还是详细和简单一点好，毕竟语言不通（日语再牛也不会比理解中文强吧）。这边的日本用户巨变态，要求机器的配置（内存和CPU）要和他的一样，环境要求一样（比如操作系统，JDK配置，tomcat版本要完全一致）。基本一个项目就要配一台专门的服务器，嘎嘎
#9238 评论作者： spenguin 发表时间：2006-03-16 04:01
能否把文档贴出来我看看啊，我没见过，呵呵
#9230 评论作者： boool 发表时间：2006-03-16 10:58
什么事情都不能一概而论，就我做了这么多年的对日开发，感觉上，大部分项目，以详实的方式来做文档，是必要的，对日外包这种外包项目，是存在语言沟通的问题的，详实的文档，会帮助开发者理解设计者的含义，在能理解能沟通的情况下，当然文档简单些好，这也是xp的初衷么。不要说去比聪明，即使牛人不写文档，我认为是不负责任的行为，我们做程序是面向服务，不是纯粹为了开发，要让客户满意，让自己的同事和公司满意，没有文档，以后不知道会多出多少麻烦，只要本着认真负责的态度，达到沟通交流说明的目的，那就应该是文档的标准了。
#9209 评论作者： zhenzhongwang 发表时间：2006-03-15 11:01
其实还有一点要补充，我们的文档全部都是Excel做成的，包括最初的要件设计，至少在这点上我是比较佩服的，呵呵
#9208 评论作者： zhenzhongwang 发表时间：2006-03-15 10:59
我个人认为至少我们现在所做的文档都是需要要的，将一个系统开发完后，教给用户，如果将来用户将系统交给其他公司来进行改造的话，光看文档就可以了，之前也改造过其他公司做的软件，很复杂，但是文档很详细，所以感觉理解起来比较容易，要说文档不爽的地方就是有的文档必须是中日文各一份：），不过也忍了。至于CMM，之前也参加过一些公司的CMM教育，但是个人认为里面有不少文档真的用处不大，有的公司过了CMM，也不见得就很规范了，国内软件真的应该好好学习一下了。
#9204 评论作者： zflying2000 发表时间：2006-03-15 05:08
写的不错，对于项目，详细的文档是必须的。最简单的，即使你很牛。你说不出来，写不出来。谁也不知道！但是没有必要分这么多次写吧！呵呵
#9203 评论作者：tanxin124 发表时间：2006-03-15 04:38
我觉得文档的详细是非常有必要的，这么做还有可能减少开发人员之间相互推卸责任的毛病。开发工具，服务器的统一，也有助于项目最后的顺利运行。我相信大家一定遇见过项目在自己的电脑上运行正常，当拿到日本那边去的时候却不能正常运行了。结果，又会花额外的时间去解决这些问题，而解决这些问题的时间，多半远远多于当初多写百来个字的时间。弊与利大家可能自己掂量了。顺便将楼下这位大哥的评论大概翻译一下：“文档是绝对有必要的。在管理方面，日本一定且绝对有着相当的优势。完整的文档是品质管理的一部分。”
#9199 评论作者：山本はちょうど求める 发表时间：2006-03-15 02:27
ファイルは必ずしなければならない。管理の方面で、日本はずっとすべてとても優位があっていたのだ。完備したファイルは品質管理の一部だ。
#9198 评论作者： liuziwei_china 发表时间：2006-03-15 02:15
我也同意zhenzhongwang的观点，国内软件公司确实有很多牛人，可惜这些牛人有一个可怕的弱点就是不爱写文档，导致公司运转极度依赖这些牛人，等这些牛人走了，软件也就该重做了。ＣＭＭ是要求很多文档，但是有些是必要的，没有设计文档，或有设计文档，但是在开发的时候随意更改实现，这样以后来的人如何进行维护呢？　虽然写文档是很痛苦，但是毕竟是对公司有益的事，我觉得应该去做。至于aaron说的界面规范的很详细，我觉得也是可以理解的，现在国内有的公司的产品，界面本身就没有一个规范，往往是程序员自己决定用什么字体，用什么风格，导致同一个公司，甚至同一个软件却有不同的界面，不同的操作习惯，不知道这样的软件拿给用户，用户应该怎样去适应。文档不是为了限制人，而是更好的规范人的行为，保证开发者有个统一的风格。至于个人的发挥，我想应该是在完成文档的过程中来发挥个人才干，而不是在文档写完之后才返回个人才能，当然了，这样肯定不适合做外包的兄弟们。
#9189 评论作者： tcmak 发表时间：2006-03-15 12:05
討論的主題還是到底那些文檔是必要呢?1) 這是別人勞動的成果, 但也就是客戶所需要承擔的成本, 做的好當然有欣賞價值, 但是客戶總有權利去控制自己想花多少錢在文檔之上2) 看看 CMM, 那要問的問題是, 是不是每次做項目都要有同樣一系列的文檔呢? 很多都可能是, 但我覺得也沒有絕對, 或者轉個角度, 為什麼每一次都要有同一系列的文檔呢? 一個文檔有用是因為它在項目上所發揮的功能, 可能是用來溝通, 可能是方便分析問題, 而去寫這些文檔的決定權利, 而不是因為什麼 Handbook 說有所以要有...為何不可以留到項目來了和客戶一起討論來決定, 反而是因為什麼 CMM 的手冊上寫了要所以就要去做呢?看來我立場才鮮明.... 其實我倒想聽聽日本那方面的原因, 也許兩國之間的語言溝通太有問題, 所以想寫多一點.... 不過看來他們是不會上來這裡的...
#9175 评论作者： HotTea 发表时间：2006-03-15 10:07
不要把“日本”两个字与所有的东西联系起来，一个文档，要有不同的人来看，可能你认为罗嗦的地方而对其他人有价值。尤其对文档的作者，是花了很长的时间来做的，考虑了很多人，很多角色的想法才做出来的，我们不要随心所欲的来批评，要有一种欣赏的眼光来对待他人的劳动成果，我们才有收获和提高。
#9171 评论作者： li_nummereins 发表时间：2006-03-15 09:00
日企的文档实际上也是迫不得已，因为上家的公司要。对日开发做过几年，现在回头看看，除了质量要求高以外，其他也一般。其实，只要建立真正的项目管理制度，文档也就不是重点了。可悲的是，国内很多人根本不搞软件工程，还老照猫画虎的学日本的式样书......
#9170 评论作者：aaron 发表时间：2006-03-15 08:59
没错，有时候我们说过度开发其实并不是指文档过多，而是有时候很多时候对日外包把精力放在很多文档中不是很重要的地方，而且大多数都是这样。比如说有时候句号要全角，有时候就要半角，同样是文字有时候要什么明清xxx字体，有时候又要simsun的，而且很多时候这些东西没有一个规范，有时候一帮人开个会就是讨论在什么地方使用什么字体......规范是需要，但是很多时候对日外包的文档只能用变态来形容，文档是用来帮助人开发的，而不是为了文档反而限制住了人了。在对日外包干过的人都有体会，的确规范但是规范的过头，而且没啥技术，适合女孩子和非计算机专业的去锻炼，但是的确不适合年轻人常呆，都现在了还成百上千的sql写死在页面里，应该好好借鉴借鉴欧美外包。
#9169 评论作者： jiangshachina 发表时间：2006-03-15 08:58
早就听说小日本做文档，极其的细致。确实和他们在其它方面的“风格”一致啊。
#9156 评论作者： zhenzhongwang 发表时间：2006-03-14 11:41
其实我觉得日本软件设计文档我们时可以借鉴的，就拿我所在公司的两个部门来说（日企和国内部），我在日企，做和日本有关的项目，文档太详细了，从要件、外部设计、内部设计、详细设计，以及后来的单体测试报告、内部连接测试、现场测试、导入等等，都有很详细的文档来对应，以前做Coder的时候，你甚至不需要设计人员给你讲解，只要去看这些文档就可以了。现在我在做设计，就体会到了做这些文档的“痛苦”，但是我个人认为这些都是必要的文档，公司现在也在搞CMM3，但其实都准备使用现在已用的文档体系。看看国内部就知道了，国内部有很多牛人，但是他们的文档实在不敢恭维，做出来的文档Coder很难一个人去看懂。个人认为日本软件设计的文档还是值得我们去好好学习的，很严谨！