代码注释 该加还是不该加?

· 代码注释是一个好习惯,从开始写代码时我就一直是这么以为的。最近阅读了很多大牛的书,然后经过大量自我的思考,我知道了,注释什么时候该加,什么时候该删。

1.注释不是"除臭剂"

· 注释 作为解释代码逻辑的手段的确很重要,特别是对于那些逻辑复杂,难以理解的部分,这可以让后续的修改者更快理解代码的初衷。
· 但是,如果代码逻辑 本身有问题,这时,注释 就成了 “除臭剂”,为了解释代码的"复杂"逻辑而存在。

· 就像,如果你的卫生间脏的难以忍受,而你只在这里放了一个除臭剂,来安慰自己能在这里待下去,这真的是应该做的吗?
· 因此,如果是这种情况,你应该勇于 修改代码逻辑,让其变得清晰和整洁。
· 不要想着,我只是在这里待一会就走,放个除臭剂没啥不好的。这样的 “忍耐力” 可能会让你更加的 平庸。没有高标准,何来大师名。这个是我对自己的告诫。

2.真的好代码

· 我总结了好代码的通俗定义: 一眼就知道代码逻辑结构,一眼就知道变量的类型和含义,一眼就知道函数的用法和参数意义。
· 要实现这个目的,有以下几个标准,我分别和打扫房间做了类比:

  1. 代码简洁 (房间一尘不染)
  2. 逻辑清晰 (家具布局合理)
  3. 函数名和变量名 规范 (家具上的物件摆放整齐)
  4. 如果逻辑复杂度不能降低,可以加注释。(如果家具并不协调,布局难以合理,可以加点装饰品来掩盖一下)

· 加了类比之后,我相信大家能更好的理解好代码含义了。

3.注释的使用场景

· 通过以上的好代码含义,我们知道了注释在 好代码 中的位置。
· 但是,这并未意味着 注释平时要少用,恰恰相反,在大多数场景中,注释应该多多使用。有如下场景:
1. 不知道该做啥;
在开始设计代码时,可能遇到不知道做什么的时候,可以用注释来表示最开始的思路 和 后续的计划,通过伪代码展示出代码的基本框架;
后续在代码完成之后,可以最后删掉大部分的注释,保留部分必要的部分。

2. 没有十足把握的时候;
· 在设计代码时,可能遇到并无很大把握的情况,特别是代码设计的"交叉路口",这个时候就需要 用注释写出 自己的思维决策过程,这样设计的原因,方便后续遇到问题时,如何回溯问题,找到解决办法。

3. 还未理解别人代码逻辑的时候。
· 在负责修改别人实现的功能时,可能遇到一些"古董级"老代码,这些代码可能逻辑复杂,代码冗长,难以理解,这个时候就可以通过代码注释来逐步理清代码的真实逻辑,
· 然后逐步的重新设计代码,当代码越来越好的时候,注释也就可以慢慢退场的。

· 最后,我们要牢记,我们重构代码的目的就是让这些注释都变得多余,直至消失。

如果觉得我的文章还有点收获,就点个赞吧! d=====( ̄▽ ̄*)b

發表評論
所有評論
還沒有人評論,想成為第一個評論的人麼? 請在上方評論欄輸入並且點擊發布.
相關文章