2019独角兽企业重金招聘Python工程师标准>>>
关于如何写好代码注释:
注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。
程序中,真实只存在一处地方:代码。应该尽量使用代码表达,而尽量减少注释。
什么样的注释才是好的注释:
1.法律信息。
2.提供信息的注释。
3.对意图的解释。提供了某个决定背后的意图(比如在程序中写入了某些“匪夷所思”的代码,提供注释来告诉阅读者这些代码的用途)。
4. 阐释。注释把某些晦涩难明的参数或者返回值的意义翻译成某种可读形式。
5.警示,用于警告其他程序员会出现某种后果的注释。
6. TODO注释 。TODO是一种程序员认为应该做但出于某些原因还没做的工作。记得定期查看TODO注释,并且完成该工作后,删除不再需要的。(我在当前的andriod团队开发中深有感触,大有益处,IDE一般也提供了寻找TODO注释的快捷途径)。
7.放大。某些注释可以用来放大某种看起来不合理之物的重要性。(通常此种注释的篇幅有多行以上,容易吸引眼球)。
8. 公共API中的Javadoc。
对一些“坏”注释的补救方案:
1.右括号注释。即有一个巨大的代码块,包含了多个if,for,while语句,出于方便在对应的右括号后加注释标识是哪个语句的结束。 —— 解决办法:缩短函数
2. 注释掉的代码。 千万别这么做,因为其他人不敢删除注释掉的代码,他们会猜测那些注释掉的代码放在那里一定有原因。
总结:
尽量少写注释,努力强化代码表达能力。