程序员的自我修养-代码注释

Source

最近公司开始代码review,使我对代码注释有了更深层次的理解。

  1. 注释首先要告诉维护的人这段代码是谁写的。
  2. 函数头注释应该描述函数调用的前置条件和后置条件。
  3. 注释不是描述代码做了什么而是描述为什么这么做。好的代码注释应该告诉后来人维护的思路。

作者在写代码时已经考虑了后续版本的需求哪里可能会变化,变化后只要怎么修改一下哪里的代码就可以支持。这样的代码注释看起来很舒心,作者是有思想的,也是负责任的。

当然,对于业务逻辑实在太复杂的部分。看代码不能一下就看出个所以然来,通过一段文字说明,把关键点点出来,还是很有好处的。

  1. 注释描述的内容应该和代码是一致的

修改代码时未同步修改注释,注释成了误导。错误的注释比没有注释更糟糕。

  1. 取一个有意义的函数名,让它自注释。

开发过程中经常看到这样的情况:某个功能要处理A,B,C三件事,拆分成三个函数,函数名就是DoA, DoB, DoC。只能说太随意了,还可以再斟酌一下,更具体一点。

  1. 取一个好的变量名,让人不易误用。
发布了45 篇原创文章 · 获赞 5 · 访问量 4295