写好注释的方法小结

2019独角兽企业重金招聘Python工程师标准>>>

关于如何写好代码注释：

  注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。

  程序中，真实只存在一处地方：代码。应该尽量使用代码表达，而尽量减少注释。

 什么样的注释才是好的注释：

1.法律信息。

2.提供信息的注释。

3.对意图的解释。提供了某个决定背后的意图（比如在程序中写入了某些“匪夷所思”的代码，提供注释来告诉阅读者这些代码的用途）。

4. 阐释。注释把某些晦涩难明的参数或者返回值的意义翻译成某种可读形式。

5.警示，用于警告其他程序员会出现某种后果的注释。

6. TODO注释 。TODO是一种程序员认为应该做但出于某些原因还没做的工作。记得定期查看TODO注释，并且完成该工作后，删除不再需要的。（我在当前的andriod团队开发中深有感触，大有益处，IDE一般也提供了寻找TODO注释的快捷途径）。

7.放大。某些注释可以用来放大某种看起来不合理之物的重要性。（通常此种注释的篇幅有多行以上，容易吸引眼球）。

8. 公共API中的Javadoc。

对一些“坏”注释的补救方案：

1.右括号注释。即有一个巨大的代码块，包含了多个if，for，while语句，出于方便在对应的右括号后加注释标识是哪个语句的结束。 —— 解决办法：缩短函数

2. 注释掉的代码。 千万别这么做，因为其他人不敢删除注释掉的代码，他们会猜测那些注释掉的代码放在那里一定有原因。

总结：

尽量少写注释，努力强化代码表达能力。

转载于:https://my.oschina.net/Bruce370/blog/536806