究竟要不要写代码注释？

Posted 2021-02-03 viaiu

看完上图你是什么反应？会骂人吗？会就对了……，代码整洁之道，是一条很漫长的路，注释是其中一部分。

如果是一个很大的方法，要不要加注释？一个大方法按照它的功能被分割成几个小方法，这样代码就比较容易阅读了，但有的童鞋说能在项目的deadline里面搞出来就行了，哪有时间整理这种大方法？为了让你的搭档或者接手者，更轻松的理解，让她/他少加班，抽时间还是整理一下吧。按照树的结构，一个主干，其他分支都是处理不同的逻辑。

如果是小方法能做到见名知意，就一定要见名知意，习惯总是要培养的，接一句鸡汤：走得慢并不要紧，只要你坚持不停地走，那么总有一天你能走到你想要到达的地方，能超过道旁那些不敢走的人。走正道！

大牛们总是说：代码就是最好的注释。可惜我还没有达到那个程度。但是我依然尝试着用命名代替注释，发现自己做的并不对，如果你团队的新人呢？比较复杂的方法，靠命名？所以这个时候还是建议把注释写的清清楚楚，其一：为了自己以后维护的方便； 其二：为了其他人接手的方便。

总结一下：

• 如果自己的英语不好

对我们来说第一语言是中文的，英语不好情况就不一样了，这就是为什么国人的建议大多要求注释详尽，让代码更易读易懂；而老外的建议几乎是尽可能的少；符合我国基本国情。

• 如果自己的水平还不够

对于很复杂的逻辑，务必用12345的顺序依次写清楚；对于函数中的某个参数，需要解释为什么要设置这个参数，尤其是公用工具类里面的函数---说清楚参数的背景含义，可以让其他调用者理解的更加清晰。

• 如果整个团队水平参差不齐

一般不要用英文写。虽然这样看起来格调很低，但胜在大家都能轻松的看懂。写代码不能太傲娇，不能太任性，写注释也不要太傲娇，目的是让你的搭档或者接手者，更轻松的理解，提高效率，早点回家老婆孩子热炕头。

我们不能保证每个团队里面的每个成员都是大神，写该写的注释，单一定要去尝试用方法名和变量名去替代注释，说不定哪一天你也成为了大神？

稍后等于永不，行动起来……