『思考』为什么老外的注释和文档普遍比国人好得多？欢迎讨论

注释和文档是程序质量的一个极其重要的部分，怎么强调也不为过

大家可能都有这样的体验：看老外的程序是一种享受，看(维护)国人的程序是一种苦差。除了编码水平的问题，注释文档是一个明显的区别：老外的注释详尽，常常是注释多于程序本身，如jdk的一些类，接口；国人的程序往往注释极少，甚至就没有。原因何在？

我们都知道注释文档的重要性，但好象又没有受到约束。很多公司提倡的代码的互测和自测只是说说而已，没有从制度上落到实处。要保证产品开发实施的延续性，这些极其重要。关于注释和文档，可能你心里很清楚(过个一年半载你不一定会清楚)，但能否清晰地表达出来，落实到字面上，这是很需要花精力的事，也是很锻炼人的事，你一定要用心去做才可能做好。对于做产品，很多时候注释和文档的重要性要大于程序本身。你有没有用全心做这件事，有没有站在看你文档和注释的人员的角度去思考这个问题，而不是仅仅写完代码实现功能了事，与你的个人素质和做事严谨性密切相关，这主要靠个人的修养和自觉(扪心自问，我有没有尽力)，但也应该从制度上督促和鼓励，使得用心踏踏实实地做这样的事的人得到认同。

时时问一句，我有没有为一起做这件事和后续做这件事的人着想，而不是仅仅狭隘地为自己着想，为赶进度而匆匆实现功能了事。

这根本就不能算是什么思考！

老外？老外的程序？老外的注释？如何界定？

除了中国人，其他都是老外。他们是一样的？他们的程序是一样的？他们的注释是一样的？

同一个国家的人、同一个地区的人，甚至是同一个公司的人，都有水平高低，写出来的程序、注释，也水平参差不齐。你怎么比？

更加可笑的就是，注释多就是好吗？注释比代码还多就是好吗？好好看看《重构》吧。注释用得不好，也不过就是一种除臭剂而已。


这是什么逻辑？去看看敏捷宣言吧！

扯蛋！看看《源代码就是设计》吧。

太高调了，悠着点，兄弟。我写文档大部分时候只是为我自己方便，便于张三工作干我鸟事。

我只不过说的是普遍现象，可能我们学习的源码都是国外程序员中水平较高的人写的，不具有可比性


这句话我说得过头了，我的原意是在实施维护阶段代码注释很重要,接受庄表伟的指正。



我不屑于与你这样的人讨论，兄弟，不管你的水平有多高(这点还未知)，做学问做技术先学会做人。

http://forum.iteye.com/viewtopic.php?t=4610

我的一篇帖子，里面讨论了一下注释问题（第二页）。

我认为大家应该转移话题来讨论产品的设计问题，这个才是我们目前所遇到的最迫切问题。
文档从来都不是一种工程化的标志，至少在可以预见的未来也不可能是。注释本身就是一种味道，当然对付日本人的最好办法就是写大量的注释。而产品的设计一直是一种无序摸索，特别是涉及概念完整性的问题更加让我们感到困难。文档、注释，以至于代码都无助于这个根本困难的解决。但是我认为存在一种结构上的抽象，大概类似架构，但是还包括很多别的具体的实现。这个东西我叫它为企业的核心资产。这个资产不能让我们去解决概念完整性的根本矛盾，但是可以让我们去降低解决根本矛盾所带来的代价。
其实我们的讨论本来可以朝向更好的方向，而不是就一下烂的已经不能再烂，讨论不知道讨论过多久，已经达成一个基本性的共识的问题，反复的去争论。作为楼主如果认为文档和注释是最重要的，他就继续最大量的写那些文档和注释好了，只要有人给他付钱。我们不提倡写，就让我们不去写那么多好啦，这只是因为我们是一些看重软件工程的人。其实最后的根本还是拿出一个高质量的（不是CMM中那个质量的概念，而是工程学上的质量概念）软件，这才是判断是非的唯一标准。

就算没有要求，作为个人也要有一个工作准则，叫职业道德也好，那就是：
不要让维护的人骂我们

我做了很多阑尾工程，最大的体会是文档基本都是垃圾，注释都是地雷。并且随着这两者数量的增大，其危害程度会成数量级的增加。所以你要不被我骂最好的办法就是写清晰的代码，完备的测试，足够少的文档。如果你准备被我骂的狗血喷头那么就开始写那些让我感到莫名其妙的注释和不知所云的文档好啦。
事情的根本原因在于一些人根本就不写文档，也不知道如何写注释，所以就对这些东西存在某种天真浪漫的幻想。当他们真正的在项目中去运行他们的想法的时候，才会理解文档和注释的维护是多么的困难和不可能，才会理解一个真正的工程是不可能建立在文档和注释的基础上的。同时这些人还总是把用户使用手册这样的文档和设计文档有意的混淆在一起，说人家怎么怎么重视文档，给人感觉似乎是所有的文档都需要大量的投入，都必须最大量的。而注释的情况更加奇怪，有些人根本就没有作过项目，或者处在一个莫名其妙的组织中（多数的CMM企业都是这样），他们提到的一些更加让你感觉哭笑不得的证据。例如某人是某CMM3的SCM经理，对我说：“你看，人家的注释写的多仔细，每一个类都是作者签名和写作日期。”最好笑的是另外一个CMM3的SCM经理也说过一样的话，而某CMM4的一个CTO还说这是国外的成熟的最打体现。对待这些外太空的人士，我是无时间和精力去和他们讨论任何有关软件开发的任何的事情。
这些人大量存在于我们的四周，做人不行，做事也不行。

在这件事情上oz6我不得不站出来批评你了。
不能用发生在你周围的事情来评论注释和文档本身。

在你讨论的过程中，“注释”和“文档”已经被偷换成了诸如“作者签名”和“写作日期”这样的概念，或者是那些为了应付差事而写的很多描述性文字。

要注意，在历史上，任何成功的新的思想，都不是站在对以前的思考的完全颠覆的基础上，而是已经能够对原有的思想熟练运用，才能够升华提高。由厚到薄，由厚到薄，这样的层次变化是不断发生的，UML是基于以前的数据流图，场景卡片等开发设计过程之上的，假若让一个从来没有分析过数据流图，从来没有和客户面对面接触过的人来画UML,或许能画的头头是道，但是在实际的面对客户的不段修改过程中，却会屡屡碰壁到头破血流。

“少写文档”，是站在已经大量写过高质量的文档的基础上。假若不开始编写文档，又如何能升华到不写文档的层次？假若说现在的文档编写得不好，充斥了无用的垃圾，只能说你们的文档工作远远没有做好，而不是说索性不写文档。我反对oz6这样不分青红皂白一棍子把文档打死的做法。

albert_qhd的这个说法我是赞成的。文档工作的目的，是为了在整个项目的开发周期中，能够跟踪到原始的信息，能够有迹可循。
我学习过日本的开发方式，我也接触过台湾的设计方式。当然我也接触过CMM5的公司。可以说，国内绝大部分使用UML,或者提倡不写文档的公司，做设计的深度和设计的工业化程度远远没有达到他们的层次。

比如说访谈纪录。有没有做到把每次和不同的客户的访谈都记录下来？这样日后才能有迹可循，才能知道站在整个系统不同层次的用户的真实需求。
XP方式简单的说：让客户在场。其实这是简化了问题，这个客户代表和他背后的整个公司是如何交流的？如果简化了这个步骤，实际上是把这种纪录推到了客户代表身上，一个负责任的客户代表仍然需要记录他和公司其他人员之间的沟通。

在比如说拥抱变化。拥抱变化，首先你要记录为什么变化。假若理解这个变化是无序的，是客户怎么说就怎么改，这样的变化是毫无意义的。外界变化是内在需求变化的表现形式，如果不知道为什么变化，绕几圈之后，又回到老路上了，所有的人都绕一个大圈，这样的变化又有什么意义？

我们在数据库中保存所有版本的设计文档；我们保存大量的修改痕迹；我认为我们的文档工作，现在逐渐踏上正轨。一个没有文档数据库的团队，是一个没有积累的团队。团队结束，作鸟兽散。
当遇到一个新的变化的时候，接手的团队如果没有这些资料，你叫他跳楼？