一场关于代码注释的争执，引发的三点思考_为什么编程的解释很难理解

先自我介绍一下，小编浙江大学毕业，去过华为、字节跳动等大厂，目前阿里P7

深知大多数程序员，想要提升技能，往往是自己摸索成长，但自己不成体系的自学效果低效又漫长，而且极易碰到天花板技术停滞不前！

因此收集整理了一份《2024年最新Golang全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友。

既有适合小白学习的零基础资料，也有适合3年以上经验的小伙伴深入学习提升的进阶课程，涵盖了95%以上Go语言开发知识点，真正体系化！

由于文件比较多，这里只是将部分目录截图出来，全套包含大厂面经、学习笔记、源码讲义、实战项目、大纲路线、讲解视频，并且后续会持续更新

如果你需要这些资料，可以添加V获取：vip1024b （备注go）

正文

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<num; i++){
System.out.Println("Sum = " + sum);
sum = current + previous;
previous = current;
current = sum;
}

其实这段代码计算的是斐波那契（Fibonacci）数列的前num个值。如果注释错了，盲目相信注释可能会南辕北辙，但是好的注释会事半功倍。

// compute the square root of num using the Newton-Raphson approximationr = num / 2；while(abs(r - (num/r) > TOLERANCE){ r = 0.5 * (r + (num/r));}System.out.println("r = " + r);
上述例子，它用来计算num的平方根，代码一般，但注释比较精准。

注释的目的

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

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

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

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

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

注释怎么写?

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

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

具体的操作手段，包括但不限于以下几点：

• 适当注释，仔细衡量，不要隐晦也不要多余；
• 注意存在变更情况是，需要及时更新；
• 注释代码中一些tricky的技巧或者特殊的业务逻辑，否则会让读代码的人摸不着头脑；
• 如果附上jira、bug、需求等的地址能够帮助理解代码，可以适当加上；
• 如果代码命名良好，结构合理，一般来说是不需要什么注释的。但是用一句话解释下意图和功能也是极好的，因为很多时候仅仅是想知道代码怎么用，读一句注释要比分析几十行代码快得多。

注释的原则

1）写注释应遵循奥卡姆剃刀原则：如无必要，勿增实体

注释写的不好、维护得不好（比如改了代码没改注释）会导致代码的可读性变差。

2）有句话叫“代码即注释”，虽然不完全是，但有道理的

把代码写好、写漂亮，注释就可以精炼，也必然能写得更易懂。此外，把思路（难的、关键的）写清楚，比啥Author、Date重要多了。抓重要信息。

3）建议注释里尽量写为什么，而不是做了什么

做了什么，看代码就好，代码不会骗人。但为什么要写成这样，有时候就非常让人困惑。有可能是处理某个corner case，有可能是绕过某个系统限制，也可能是什么奇葩需求，这种代码，没有当时的 context，过几个月看，像甲骨文一样，不知道是想干什么。再有看不顺眼来优化一下，以后就不知道哪个地方会崩了。

网上学习资料一大堆，但如果学到的知识不成体系，遇到问题时只是浅尝辄止，不再深入研究，那么很难做到真正的技术提升。

需要这份系统化的资料的朋友，可以添加V获取：vip1024b （备注Go）

一个人可以走的很快，但一群人才能走的更远！不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人，都欢迎加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！
V获取：vip1024b （备注Go）**
[外链图片转存中…(img-RJTRt3GD-1713447593467)]

一个人可以走的很快，但一群人才能走的更远！不论你是正从事IT行业的老鸟或是对IT行业感兴趣的新人，都欢迎加入我们的的圈子（技术交流、学习资源、职场吐槽、大厂内推、面试辅导），让我们一起学习成长！