王辉的博客

禁止注释

在博客里,我很少会提到IT技术方面的问题。一是觉得这些东西会很晦涩,不易理解。更主要的是,限于自己的境界,很多想说的话都已经被人给说过了,吃别人嚼过的东西,指定是越嚼越无味。

至于第一个限制,我可以试着慢慢更改,毕竟博客不是写给所有人看的,能遇到一些同行,做些真正深入的交流,总归是一件幸事。至于第二个原因,我仍会很大程度上的去坚持,尽最大努力,不写重复性的东西。但偶尔站在巨人的肩膀上,看到的一些趣事,也许值得用几行文字,做个留念。

实习的时候,老鸟们告诉我,写代码前先写注释,把要做的事情,先用文字表达出来,然后再编码。工作了以后(公司的确是换了),读着老鸟们写下的代码,却没有找到半行注释。彷徨在这个矛盾前,我不禁想问个为什么?

后来,同事告诉我,其实也是别人告诉他的,之所禁止写注释,是担心,有时候代码改了,却忘记更新相应的注释。如此以来,注释反而误导了不明真相的观众,搞的画蛇添足,什么都不是。

这种解释确实有它一定的道理,假如说代码本身(类名,函数名等)已经很清楚的表达了,注释想表达的意思,那么就没有必要去重复这种信息。重复的严重后果是,一旦修改其中一个,另一个必须时刻保持同步,做相应的改动。

这是原因之一,另外还有一个,是受“巨人”Martin Fowler的Refactoring: Improving the design of existing code的启发。书中在重构函数一章中提到,如果一个函数中的几行代码需要用注释去表达它的用途的时候,往往说明 ,我们需要用这几行代码新建一个函数,并以注释本身去命名这个新函数。

引用其中一简单例子:

这样做,我们略去了注释,而且还增加了代码的可读性,和可再次利用性,使代码更加简洁和稳定。

但也有例外,特别是当我们要解释做某件事的动机,而不是停留在描述某件事的行为的时候,注释就可以帮助更快的理清脉络。

代码好不好,不在于注释多不多,而在于注释是在画蛇添足,还是在画龙点睛。

王辉 wechat
订阅王辉的博客,请长按或扫描上方微信二维码