|
该帖已经被评为精华帖
|
|
|---|---|
| 作者 | 正文 |
|
发表时间：2004-07-19
ozzzzzz 写道 我做了很多阑尾工程，最大的体会是文档基本都是垃圾，注释都是地雷。并且随着这两者数量的增大，其危害程度会成数量级的增加。所以你要不被我骂最好的办法就是写清晰的代码，完备的测试，足够少的文档。如果你准备被我骂的狗血喷头那么就开始写那些让我感到莫名其妙的注释和不知所云的文档好啦。
事情的根本原因在于一些人根本就不写文档，也不知道如何写注释，所以就对这些东西存在某种天真浪漫的幻想。当他们真正的在项目中去运行他们的想法的时候，才会理解文档和注释的维护是多么的困难和不可能，才会理解一个真正的工程是不可能建立在文档和注释的基础上的。同时这些人还总是把用户使用手册这样的文档和设计文档有意的混淆在一起，说人家怎么怎么重视文档，给人感觉似乎是所有的文档都需要大量的投入，都必须最大量的。而注释的情况更加奇怪，有些人根本就没有作过项目，或者处在一个莫名其妙的组织中（多数的CMM企业都是这样），他们提到的一些更加让你感觉哭笑不得的证据。例如某人是某CMM3的SCM经理，对我说：“你看，人家的注释写的多仔细，每一个类都是作者签名和写作日期。”最好笑的是另外一个CMM3的SCM经理也说过一样的话，而某CMM4的一个CTO还说这是国外的成熟的最打体现。对待这些外太空的人士，我是无时间和精力去和他们讨论任何有关软件开发的任何的事情。 这些人大量存在于我们的四周，做人不行，做事也不行。 呵呵，一不小心引来了一大堆的批判。 我的项目经验不够，级别也不高，没有遇到CMM4经理这样的人。若是这样看待注释和文档的话确实是太务虚了，该批。 感觉注释应该注重why,而不是what，what可以由清晰的代码体现 如果注释和文档是垃圾的话，宁可不要；体现作者设计思想，高屋建瓴的文档多多益善。 我们做一些通用的小组件，供项目使用。有感而发是因为我们一个个的组件功能都很好，但在各个项目使用过程中由于文档注释、示例不全不清晰导致大量交流成本的浪费，二次开发人员普遍对不详细不清晰的文档不满，甚至造成了对组件质量的怀疑，所以才发出了只适用于特定情况下的“很多时候注释和文档的重要性要大于程序本身”的感叹，这个帖子应该发在公司内部，罪过罪过：） 以后发帖子要三思而后发了，虚心接受各位高手的指正ing |
| 返回顶楼 | |
|
发表时间：2004-07-19
to:曹晓钢
不知你是否同意敏捷建模的一些观点。 有很多文档，是可以丢弃的。哪怕再有价值的文档，如果不是对软件开发（特别是对于编写真正的程序）有价值。都是可以丢弃的。 |
| 返回顶楼 | |
|
发表时间：2004-07-19
albert_qhd 写道 不要让维护的人骂我们
这也是我写文档的原因之一，因为我很怕麻烦。如果我写的一段代码被几个程序初哥使用，这些蠢蛋三天两头来问我，我烦也要烦死了，还做什么正事？所以干脆写一个详细的 FAQ 给他们。但是我从来不主动出于利他的动机来写文档。即使我写文档来帮助初学者，也是因为我在这个团体中，我希望这个团体有好的前途。如果大家水平都提高了，对我也会有好处的。主观为自己，客观为他人，能做到这点就不错了。 我觉得大家的分歧在于究竟是写大量正式的文档（必须严格遵照模板，而且文档规范性还要作为绩效考核的因素之一），还是写一些不拘形式的，非常实用的文档（HowTo、FAQ，etc.）上面。曹晓钢支持前者，而 o6z、庄表伟支持后者。 我不喜欢日本人的开发方式，我也不喜欢每天大部分时间浪费在案牍工作之中。编程才是令我最感兴趣的工作。就算你说破天我也认为软件的核心价值在于代码而不是文档。想办法努力通过重构使你的代码结构清晰，易于理解和维护才是最重要的。否则即使你写的注释比代码还要多，文档写的辞藻再华丽，其实都不过是一大堆“除臭剂”而已。这个没什么好争论的，看过《重构》的人都知道这已经是软件业的定论了。 |
| 返回顶楼 | |
|
发表时间：2004-07-19
庄表伟 写道 to:曹晓钢
不知你是否同意敏捷建模的一些观点。 有很多文档，是可以丢弃的。哪怕再有价值的文档，如果不是对软件开发（特别是对于编写真正的程序）有价值。都是可以丢弃的。 我并没有如“没有人”所说，支持正规的文档，并且作为绩效评估，并不是说我学习过日本人的文档，就完全照搬。 “哪怕再有价值的文档，如果不是对软件开发（特别是对于编写真正的程序）有价值。”这句话本身就是矛盾。 我反对的并不是敏捷，我反对的是oz6把文档都打倒的做法。你的文字也语焉不详，并没有指出什么是“对编写真正的程序有价值”的文档。比如说界面设计是不是？界面设计是和程序紧密相关的吧，如果界面设计是，那么需求的访谈纪录是不是？如果访谈纪录是，那么变化的记录是不是？ 敏捷的初衷是,选择适合程序员自己的开发方式. 我并不希望初学者读到这个帖子,大喜到,太好了,牛人们都说不需要写文档的,我的经理还要教我写,他是个神经病! 停住,老老实实写文档去,先把基础的事情做好再说. |
| 返回顶楼 | |
|
发表时间：2004-07-19
在这个帖子中,我更加觉得奇怪的是一种盛气凌人的气氛.对不起,在这个世界上并不是有些人比另一些人懂得多多少.
从理论上,我们知道的这些东西,都是从书上学习来的,别以为书在这里,你读过别人没读过. 而从实践上得到的经验,我相信并不是每个人都知道的有我多,都有资格和我讨论这种问题. 在论坛上尊重别人是一种最起码的道理. 对于楼主的积极思考,我是持支持态度,而对于庄表伟的第一个跟贴和后来oz6的发言,我深表失望. |
| 返回顶楼 | |
|
发表时间：2004-07-19
我觉得 o6z 有点象五四时期的胡适，喊出了“打倒孔家店”的口号。当时孔家店究竟该不该打倒？应该打倒，因为当时封建伦理道德严重桎梏了中国知识界的思想。但是现在我们知道儒教的糟粕都是后来程朱理学所带来的，其实孔子本人的思想还是很好的。
其实现在敏捷的思想在中国如同初生的嫩芽，根本没有形成气候，更谈不上成为主流，相反 CMM 等一些落后的开发方式到是大行其道。 从这个角度来看，我支持 o6z 的说法。我觉得曹先生是有些过虑了。不是 o6z 说了什么我们就会当作圣经的。 我的一些用语不当的地方，希望诸位海涵。不过是个论坛，没有必要斗什么气。 Good luck! |
| 返回顶楼 | |
|
发表时间：2004-07-19
曹晓钢 写道 我并没有如“没有人”所说，支持正规的文档，并且作为绩效评估，并不是说我学习过日本人的文档，就完全照搬。
“哪怕再有价值的文档，如果不是对软件开发（特别是对于编写真正的程序）有价值。”这句话本身就是矛盾。 我反对的并不是敏捷，我反对的是oz6把文档都打倒的做法。你的文字也语焉不详，并没有指出什么是“对编写真正的程序有价值”的文档。比如说界面设计是不是？界面设计是和程序紧密相关的吧，如果界面设计是，那么需求的访谈纪录是不是？如果访谈纪录是，那么变化的记录是不是？ 敏捷的初衷是,选择适合程序员自己的开发方式. 我并不希望初学者读到这个帖子,大喜到,太好了,牛人们都说不需要写文档的,我的经理还要教我写,他是个神经病! 停住,老老实实写文档去,先把基础的事情做好再说. 首先要承认，“哪怕再有价值的文档，如果不是对软件开发（特别是对于编写真正的程序）有价值。”这句话是有语病的。确切的说法应该是：“文档的价值，只能通过是否有利于代码开发来判断。” 其次，敏捷建模这本书，如果你看一看的话，我们的交流能减少很多误解。 再次，可丢弃的文档，并不等于不需要写的文档。这有很大的区别。文档的价值，并不是永恒的。一份文档，在有利于代码开发的时候，当然值得保留。但是如果已经失去价值了，就应该尽快丢弃。 所以，我可没有说不需要写文档。也许按照传统的写文档的方法，1000页的文档，只需要你花100个小时的时间。而现在，我赞同只需要写100页的文档，但是这100页的文档要写得好，可能也需要花你100小时的时间。 所以，我并不是像ozzzzzz那样，把文档都打倒的思路。但是我也不同意你的，把所有的纸头都保留下来“珍而重之”的思路。 |
| 返回顶楼 | |
|
发表时间：2004-07-19
没有人 写道 其实现在敏捷的思想在中国如同初生的嫩芽，根本没有形成气候，更谈不上成为主流，相反 CMM 等一些落后的开发方式到是大行其道。
你认为CMM就是落后的,敏捷,XP就是先进的吗? 稍候,请重新翻出你的"敏捷软件开发：原则、模式与实践",翻到第二章,请重新读一下标题下面的这一句话: " 作为开发人员，我们应该记住，XP并非唯一选择。 ——Pete MaBreen " 如果我说敏捷也可以用到CMM,你相信不相信? 除了敏捷,还有Lean Programmer现在也很火,你知道不知道他的思想是脱胎自日本人的? 一叶障目,别太自以为是. |
| 返回顶楼 | |
|
发表时间：2004-07-19
我觉得需求文档是必须跟踪的，而且最好是客户签了字的那种，万一将来要重新核算项目时间和成本的时候最有用。
总体设计文档、数据库设计文档是必须有的，而不是一大堆程序和powerdesign。程序和那些图只是告诉了别人设计的最细节结果，而不是应用组织的骨架和为什么那么做。很多设计都有隐含的权衡在里面，不写出来会害死人。 |
| 返回顶楼 | |
|
发表时间：2004-07-19
庄表伟 写道 所以，我并不是像ozzzzzz那样，把文档都打倒的思路。但是我也不同意你的，把所有的纸头都保留下来“珍而重之”的思路。
赫赫,我并没有"把纸头都保留下来",相反,我们的文档全都是电子的.更重要的是,我们有自己的管理工具,有文档的CVS, 也有自己的knowledge base, 还有bug trace 数据库,这些都支持全文检索. 变化本身,对项目来说也是一种宝贵的财产. |
| 返回顶楼 | |
