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

     o6z兄，首先我想说明几点，第一、代码审查有几个方面：代码规范化检查、代码质量检查，代码符合性检查，在前两种，大部分工作可以通过工具完成，符合性检查是什么，它主要是对一些程序逻辑进行设计与实现的符合性检查（它不同于单元测试）。一个算法如果没有注释，没有说明，能有几个人看得懂？（冒昧地问一句，我放一个样条曲线多维方程的实现，没有注释，哪个可以看懂？），完全没有注释分复杂程序根本就是在卖弄，甚至是在破坏整个团队。 第二，我说过，程序注释分为声明式的注释和解释型的注释，对于解释型的注释不存在什么标签的使用问题的。第三，追求代码清晰和编写注释是完全不冲突的事情，如果代码足够清晰易懂，自然可以少注释甚至不注释的。但是问题，谁可以做到？谁可以做到自己写的代码什么情况下都清晰易懂，谁可以做到自己的代码可以完全符合当初的想法而没有潜在的逻辑问题？而这样的情况不需要注释么？
    我从来没有说过要大量注释，我是提出适当注释，也就是遇到复杂逻辑的时候，应该予以注释，不仅仅是为了自己，更是为了大家。我觉得这个帖子的回帖充满了激进的论调，符合了那些喜欢卖弄自己程序人的想法，在现实中的被强制放到了网上来宣泄。但是有没有想过，这样，反而会害了更多的人！

    让我回答楼上的问题，首先，楼上做了几个假设。可运行代码，这个自然不用说了，代码都不能运行还谈什么？单元测试和其他测试，也不用说了。而这些都和注释不注释没有更多瓜葛。注释的目的是什么？不是为了现在的自己，而是为了将来的他们（也许包括自己）。我想问，如果到后来测试出现问题，需要修改代码，这个时候，乱糟糟的代码，毫无注释，谁想改？第三，你提的代码清晰简洁，我就想问，谁能保证什么情况都可以清晰简洁？而且你认为的清晰简洁，在别人眼中是否又是这样，在将来的你回头看的时候是否又是这样？一个人在编程能力趋向稳定之前（而这需要三到五年的时间，大家当中有几个？）代码的编写能力都是提高的，回头看自己任何的代码都觉得不够清晰不够简洁，这说明什么？最后，算法流程可以用UT代替么？根本不可能的事情，举个例子，树的查询，可以用深度优先查询，可以用广度优先，UT可以测出来？UT关注的是路径测试、边界测试、功能测试，和怎么实现扯不上太多联系（当然，如果你用工具进行DEBUG那是另外的话）。
    改好的函数遇到改注释就烦了，这是90％以上的程序员会发生的情况，就因为这样而反对么？我就不信，多写那么几十个字能花掉你几分钟的时间。
    在这里，我劝那些不是有非常经验的人，不是完全能够把握这些度的人，好好的，扎实的写好程序，写好注释，这对你，对你的同事都是相当有帮助的。我敢说，不需要多久，你的水平可以大大提高（远远超过那些只喜欢做新的东西，只喜欢追求新概念的人）。
    我有过来的经验，也有身边的对比，更在这样培养我的下属，我希望大家在讨论的时候更多保持一份冷静。

to 凤舞凰扬：
兄弟，你太自以为是了，而且因为有了一点位子飘飘然而愈加自以为是。我觉得你现在比起 Kent Beck、Martin Fowler 高的已经不是一点点了，简直就是一个天上一个地下了。我们中国出了一个如此伟大的软件工程专家，干吗还要听老外的啊？凤大师真不愧是人中之凤啊！

小人之见！

我可以做到。因为我会用测试来驱动开发，我会不断重构。如果看我的方法名还不足以了解这个方法的用途，如果看我的测试还不足以明白这个方法的用法和各种边界情况，那要么是我的表达能力有问题，要么是对方的理解能力有问题。在这种情况下，我不认为有任何其他办法可以帮助我们沟通。注释难道能比（经过重构的）方法名和测试用例更清晰？除非那个读者看不懂程序。



我不能保证。但读者也可以添加他的单元测试，那么就没有“潜在的”逻辑问题了，他想知道的都可以明白地看到结果。更重要的是，测试是可执行的。你可以在命令行敲ant，然后就知道这个class有什么功能没有什么功能。而注释，我有什么理由去相信它？当然在理想状态下我可以相信注释的作者，但那毕竟也是一个人，一个像我一样懒惰（或者更懒惰）的人，我有什么办法知道他的注释是和代码同步的？

本想看看gigix写的G-roller代码够不够在没有注释的情况下看懂，结果那个什么联盟网站上不去

注意到本贴有变味的倾向，讨论到此结束。
如果有相关的技术讨论，请另外开贴。

非技术讨论就免了吧。