什么也比不上放置良好的注释来得有用,什么也比不上乱七八糟的注释更能搞乱一个模块.没有什么能比陈旧,提供错误信息的注释更有破坏性.如果编程语言能有足够的表达力,我们便最好不要写注释,因为没有多少程序员在维护代码时愿意花大量的时间和精力修改注释.久而久之,原有的注释便会失去代码所表达的含义.
如果发现自己需要写注释表达含义,想想是否可以用代码代替表达.不准确的注释比没有注释坏的多.只有代码能忠实地告诉读者它做了什么事情.所以,唯一真正的好注释就是不去写注释,不断美化代码来表达含义.
好注释
法律信息
有些公司代码规范要求编写与法律有关的注释.例如,版权和著作权申明必须放在某些文件的开头注释.
提供信息的注释
用注释提供基本信息,比如:方法的前提信息,后续处理注意事项等等.这类注释有时管用,但,如果可以用函数名代替,尽量用代码表达含义.
对意图的理解
在注释里写明代码这么处理的意图.
阐释
注释陳某些难懂的参数或返回值的意义翻译为可读形式,也许会有用.通常,更好的方法是尽量让参数或返回值自身就足够清楚.但,如果返回值是某个标准库的一部分或者是不能修改的代码,帮助阐述其含义的注释就会有用.但,添加的注释一定要保证其正确性.
警示
有时,警告其他程序员会出现某种后果的注释也是有用的.特别是强调某种不合理的操作.
坏注释
喃喃自语
很多注释似乎写出来是开发者提醒自己应该要怎么做之类的,其实这些注释是无谓之举.
多余的注释
这些注释没有说明代码的意义,也没有给出代码的意义和逻辑,甚至读它比读代码更耗精力和时间.
循规蹈矩式注释
所谓每个函数都要有注释,每个类都应该有一致性的注释,这完全是不对的.代码本身具有解释性还要注释干啥?
括号后面的注释
很多注释需要添加在一个循环嵌套另一个循环的地方,不然过多的嵌套会乱花我们的眼睛.或许我们可以尝试重构代码,减少循环嵌套了.而不是一味添加注释.
归属和署名
很多代码文件拥有作者署名,似乎这样可以说明这个文件某个作者最熟悉,其他人碰到问题可以和他讨论.但事实情况是代码修改了一遍又一遍,最后的代码连作者本人也不认识了.
注释掉的代码
很多代码被注释,它就永远在那边静静呆着了.注释掉的作者不删掉,其他人也不敢删,担心是否还有某种用途.所以,注释掉的代码比真正的注释还要难对付,该删时还是及时删掉吧.
不明显的联系
注释和代码之间的联系显而易见,很多注释放置的位置让人摸不着头脑,找不到对应的代码块.这需要注意.
注
这里仅仅给出了部分注释的好坏情况,如果有疏忽请留言提醒.谢谢!
网友评论