关于代码注释的理解

本篇内容介绍了"关于代码注释的理解"的有关知识，在实际案例的操作过程中，不少人都会遇到这样的困境，接下来就让小编带领大家学习一下如何处理这些情况吧！希望大家仔细阅读，能够学有所成！

在一次研发沟通会上，大家关于是否需要代码注释做了一番争执(讨论)。

主要内容简述如下：

A：我提议项目应该有个注释，我们有些程序员几乎从不注释代码，谁都知道没注释的代码是没法阅读的。

B：我觉得注释没必要，注释被当做万灵药，可是任何实际编码过的人都知道，注释反而会使代码更难读懂。注释很容易产生大量的废话，而编码语言相对简明扼要得多。

C：是这么回事。假如代码不清晰，又怎能注释的清楚呢?再说，代码一变，注释就过时。要是误读了过时的注释，可能又会踩坑了。

C 接着说：另外，注释过多的代码更难读懂，这样增大了阅读量。已经有一堆代码要去读了，何必再去读一大堆注释呢?

A：编辑器要知道的东西全在代码中?二进制文件里面吗?争论注释有无价值干啥呢?

B：我反对注释主要是觉得浪费资源。

D：也不能这么说，注释可能会被滥用，但是注释用得好时却妙不可言。另外，在我的工作经历中，有注释和没注释的我都维护过，我个人还是更愿意维护有注释的代码。最后补一句：尽管没必要制定注释的标准，但是我还是提倡大家注释好自己的代码。

........

关于是否加注释争执讨论比较久，最终大家统一了如下决定：

"提倡加注释，但不能滥用。我们开发流程中会有Code Review过程，这样每个人都将了解好的注释是什么样的，同时你遇到不好的代码注释，也需要告诉他如何改进。"

问题思考

作为研发同学，对于代码"注释"其实并不陌生。它往往作为我们代码文档的特殊补充而存在。

其实在代码文档中，起主要作用的因素并非注释，而是好的编程风格。

编程风格包括：良好的程序结构、易于理解的方法、有意义的变量名和子程序名、常量、清晰的布局，以及最低复杂度的控制流及数据结构。

会后我就在反思：那注释真的是以啰嗦的方式又重复一遍代码，所以没有用么?

好注释可不是重复代码或者解释代码，它会让作者的意图更清晰，注释应该能在更高的意图上解释你想干什么。

日常的注释

一般情况下，注释写的糟糕很容易，写的出色就很难了。注释不好只会帮倒忙。

我们来看几个例子：

// write out the sums 1..n for all n from 1 to num current = 1； previous = 0； sum = 1； for(int i=0; i
适当注释，仔细衡量，不要隐晦也不要多余;
注意存在变更情况是，需要及时更新;
注释代码中一些tricky的技巧或者特殊的业务逻辑，否则会让读代码的人摸不着头脑;
如果附上jira、bug、需求等的地址能够帮助理解代码，可以适当加上;
如果代码命名良好，结构合理，一般来说是不需要什么注释的。但是用一句话解释下意图和功能也是极好的，因为很多时候仅仅是想知道代码怎么用，读一句注释要比分析几十行代码快得多。
注释的原则
1)写注释应遵循奥卡姆剃刀原则：如无必要，勿增实体
注释写的不好、维护得不好(比如改了代码没改注释)会导致代码的可读性变差。
2)有句话叫"代码即注释"，虽然不完全是，但有道理的
把代码写好、写漂亮，注释就可以精炼，也必然能写得更易懂。此外，把思路(难的、关键的)写清楚，比啥Author、Date重要多了。抓重要信息。
3)建议注释里尽量写为什么，而不是做了什么
做了什么，看代码就好，代码不会骗人。但为什么要写成这样，有时候就非常让人困惑。有可能是处理某个corner case，有可能是绕过某个系统限制，也可能是什么奇葩需求，这种代码，没有当时的 context，过几个月看，像甲骨文一样，不知道是想干什么。再有看不顺眼来优化一下，以后就不知道哪个地方会崩了。
其实，大部分的代码应当是不言自明的，不需要注释的。
总结
好的注释才有价值
该不该注释是个需要认真对待的问题。差劲的注释只会浪费时间。好的注释才有价值。注释的位置可以在：变量特定的含义和限制、某个职责代码块的开始、一般控制结构的开始、子程序调用处、方法开始处描述功能、类开始处描述功能。
源代码应当含有程序大部分的关键信息。
只要程序依然在用，源代码比其他资料都能保持更新，故而将重要信息融入代码是很有好处的。
好代码本身就是最好的说明
如果代码太糟，需要大量注释，应先试着改进代码，直至无须过多注释为止。
注释应说出代码无法说出的东西
例如概述或用意等信息。注释本身应该包含的是对代码的简洁的抽象概括，而不是具体代码的实现细节。
注释风格也应该简洁易于维护
有的注释风格需要许多重复性劳动，应舍弃之，改用易于维护的注释风格。
"关于代码注释的理解"的内容就介绍到这里了，感谢大家的阅读。如果想了解更多行业相关的知识可以关注网站，小编将为大家输出更多高质量的实用文章！