一场关于代码注释的争执

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

主要内容简述如下：

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

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

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

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

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

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

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

........

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

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

问题思考

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

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

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

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

好注释可不是重复代码或者解释代码，它会让作者的意图更清晰


 

释的第一目的是帮助人理解代码，理解作者的意图。

所以优秀的代码本身就有自说明功能，只有在代码本身无法清晰地阐述作者的意图时，才考虑写注释。

即是：注释应该表达我的代码为什么要这么做，而不是表达我的代码做了什么。

我们软件开发过程中引入了那么多的设计模式、框架、组件，开发过程制定了那么详细的设计规范、编码规范、命名规范、很大一部分原因就是为了提高代码的可读性。

编程语言特别是高级编程语言，本身就是人和机器之间沟通的语言，语言本身就要求满足人的可读性，需要用符合我们自然语言的表达习惯，不需要额外的注释。

注释怎么写?

当然，好代码 > 差代码+好注释，好的注释是很有价值的，坏注释不仅浪费时间还可能有害，自解释的代码最好。

当然，好代码 > 差代码+好注释，好的注释是很有价值的，坏注释不仅浪费时间还可能有害，自解释的代码最好。好的注释不是重复代码或解释它，而是使代码更清楚，注释在高于代码的抽象水平上解释代码要做什么事。

（编辑：东莞站长网）

【声明】本站内容均来自网络，其相关言论仅代表作者个人观点，不代表本站立场。若无意侵犯到您的权利，请及时与联系站长删除相关内容!