本文转载自微信公众号《架构改进之路》，作者的架构精炼之路。转载本文请联系建筑改良之路公众号。在一次研发沟通会上，大家对是否需要代码注释产生了争论（讨论）。主要内容简述如下：A：我建议项目要有意见。我们的一些程序员几乎从不注释代码。大家都知道没有注释的代码是无法阅读的。B：我觉得没必要评论。注释被认为是灵丹妙药，但真正编码过的人都知道，注释会使代码更难阅读。注释很容易产生很多废话，而编码语言则相对简明扼要。C:是这样的。代码不清晰，注释怎么能清晰呢？此外，一旦代码更改，注释将过时。如果你误读了一个过时的笔记，你可能会再次卡住。C接着说：另外，注释太多的代码更难阅读，增加了阅读量。已经有一堆代码要看，何必再看一大堆注释呢？A：编辑器需要知道的一切都在代码中？它在二进制文件中吗？为什么要争论评论的价值？B：我反对评论主要是浪费资源。D：你不能这么说，注解可以被滥用，但注解用得好也是美妙的。另外，在我的工作经验中，我维护过注释和非注释代码，我个人更喜欢维护注释代码。最后一句：虽然没有必要制定注解标准，但我还是鼓励大家对自己的代码进行注解。.....就是否加注解进行了长时间的讨论，最后大家统一了如下决定：“提倡加注解，但不能滥用。我们在开发过程中会有一个CodeReview流程，让每个人都会很好地理解有什么样的注释，当你遇到糟糕的代码注释时，你也需要告诉他如何改进。”问题思考作为研发专业的学生，??我对代码“注释”并不陌生。它通常作为我们代码文档的临时补充存在。事实上，在代码文档中，主要因素不是注释，而是良好的编程风格。编程风格包括：良好的程序结构、易于理解的方法、有意义的变量和子程序名称、常量、清晰的布局以及控制流和数据结构的最小复杂性。会后我在想：注释真是在长篇大论地重复代码，这么没用？好的注释不是重复代码，也不是解释代码，这样会让作者的意图更加明确，注释应该可以更详细的使用。用高度的意图解释你想做什么。日常评论一般来说，写烂评论容易，写好却难。糟糕的注释是一种伤害。让我们看几个例子：//writeoutthesums1..nforallnfrom1tonumcurrent=1;上一个=0；总和=1；for(inti=0;iTOLERANCE){r=0.5*(r+(num/r));}System.out.println("r="+r);上面的例子，就是用到了计算num的平方根，代码很笼统，但是注释更精确。注释的目的是写代码，注释的首要目的是帮助人们理解代码，理解作者的意图。如此优秀的代码本身是有自解释功能的，只有当代码本身不能清楚说明作者的意图时才考虑写注释。即：注释应该表达为什么我的代码这样做，而不是我的代码做了什么。我们的软件开发这么多设计过程中引入了模式、框架、组件，所以在开发过程中制定了详细的设计规范、编码规范、命名规范，很大一部分原因是为了提高代码的可读性。编程语言，尤其是高级程序设计语言，本身就是一门l人机交流的语言。语言本身需要人类的可读性。它需要使用符合我们自然语言的表达习惯，不需要额外的注释。如何写评论？当然，好的代码>坏的代码+好的评论，好的评论很有价值，坏的评论是浪费时间而且可能有害，不言自明的代码是最好的。当然，好代码>坏代码+好评论，好的评论是有价值的，坏的评论不仅浪费时间而且可能有害。自我解释的代码是最好的。好的注释不会重复代码或解释代码，而是让代码更清晰。注释解释了代码应该在比代码更高的抽象层次上做什么。具体操作手段包括但不限于以下：适当评论，慎重衡量，不晦涩冗长；关注变化的存在，需要及时更新；在代码中注释一些取巧的技巧或特殊的业务逻辑，否则会使阅读代码的人感到困惑；如果附上jira地址、bug、需求等有助于理解代码的，可以适当添加；如果代码命名和结构良好，一般来说，不需要注释。但是用一句话说明意图和作用也是非常好的，因为很多时候你只想知道代码是怎么用的，看一篇评论比分析几十行代码要快得多。注释的原则1）编写注释要遵循奥卡姆剃刀原则：如非必要，不添加实体注释编写和维护不当（如改代码不改注释）会导致代码可读性差。2）有句话说“代码就是注释”。虽然不完全正确，但是如果代码写得好漂亮，注释可以细化，写得更通俗易懂。此外，写出想法（困难的和关键的）显然比作者和日期重要得多。掌握重要信息。3）建议在注释里尽量写why，而不是whattodo，看代码就行，代码不会骗人。但是为什么要这样写，有时候会让人很疑惑。可能是为了应对某个cornercase，可能是为了绕过某个系统限制，也可能是一些奇葩的需求。这种代码当时没有上下文。几个月后，它看起来像甲骨文。我不知道它想做什么。.不喜欢就优化，不知道以后会崩到哪里去。事实上，大部分代码应该是不言自明的，不需要注释。总结好的评论很有价值。评论要不要认真对待，这是一个需要认真对待的问题。差评只是浪费时间。好的评论很有价值。注释的位置可以是：变量的具体含义和限制，一个责任代码块的开始，一般控制结构的开始，子程序的调用，方法开始的描述函数，说明在课程开始时发挥作用。源代码应该包含大部分程序的关键信息。只要程序仍在使用，源代码就比其他资料更新，因此将重要信息合并到代码中是有益的。好的代码本身就是最好的陈述。如果代码糟糕到需要大量注释，请尝试改进代码，直到不需要太多注释为止。注释应该说出代码无法表达的内容，例如概述或意图。注释本身应该包含代码的简洁抽象，而不是具体代码的实现细节。注释样式也应该简洁易维护。一些注释样式需要大量的重复性工作，因此应该丢弃它们并用易于维护的注释样式取而代之。作者：架构求精之路，专注于软件架构研究、技术学习和个人成长。
