如果把开发过程比作开车,那么代码的注释就相当于路边的指示牌。注释是辅助的信息,并不影响程序的最终执行结果。
一个好的代码注释会减少开发周期,比如帮助下一个接手的开发人员快速熟悉代码。
不好的代码注释则反过来影响了开发过程,因为可能会误人子弟,指错路。
所以,注释并不总是好事。
曾经有一个实验,就是随机抽取一个软件程序,在里面设置一些BUG,然后让一些小组去查找这些BUG,有趣的是50%的小组都会彻底删除软件中的注释。结果是,不使用注释的小组在更短的时间内发现了更多的BUG。
我们在代码中会碰到各种各样的注释。一些注释仅仅是开发人员即兴之作,一些表名了他们有多聪明!一些仅仅是一个玩笑。
例如:
//当我写这些的时候,只有上帝和我能懂 //现在,仅仅上帝能懂了 //我来为下列代码负责... //是他们强迫我写的,我不是自愿的 //我要找一个更好的工作 try { ... }catch(SQLException ex) { //不用多说了,你很拧巴吧 }catch(Exception ex2) { //如果你想你已经拧巴过,那么恭喜你,这次更加新鲜 }
写文档性的代码而不是注释!
写文档型的代码要求你定义变量、类、枚举类型等的名字的时候会考虑别人能否看懂,文档型的代码会让其他程序员很好理解。好的文档型的代码和注释的效果是一样的,而且这减少了开发时间(不用花时间维护不知所云的注释了)。
实际上,是不是文档型的代码并不是你说了算,而是别人评价的。
另外,代码的注释即使写的很好,也会很快过期,因为软件的需求变化很快,你很难保证注释一直都是最新的,但是代码肯定是最新的。
解决方法
如果你没有足够的时间维护代码的注释,那么请不要写注释。这样你会更加有效率,你不会浪费时间写没有意义的注释。
写文档型的代码会帮你和你的下任理清思路,那些认为自己没有时间写文档型的代码的认识是绝对错误的。
当你发现一些注释看不懂或者有误的时候,请直接删除。