Yuguo.us

避免注释

Introduction

user

余果

全栈工程师,《Web全栈工程师的自我修养》作者。


Featured

back-end

避免注释

Posted by 余果 on .

前段时间我准备开源33pu的代码的时候,觉得自己的代码不够清晰,所以加上了大量的phpdoc注释。

phpdoc注释类似javadoc注释,是一种格式严格的注释风格,在每一个class和function上都需要有phpdoc注释说明function的意图、参数、返回值。我开始做这件事的时候觉得新鲜而有趣,更重要的是内心充满了神圣的自豪感——我在使代码更好。

但是随之我开始觉得无聊,我的很多function都是非常简短的,3行代码,用了不错的function命名,在这种情况下phpdoc显得冗长而没有必要,而且让源码的行数大大增加。

另一个问题是代码的维护开始变得麻烦,我需要拆分出新的function的时候,以前function的phpdoc,包括描述、参数、return往往会过期,而我会总是忘了同时修改代码和注释。就像我前一篇文章说的,重复是一切恶的来源。 《代码整洁之道》第四章“注释”对javadoc进行了批评,他认为所有非公开API的代码加上javadoc都是没有必要的。他的原话是“八股文”,“可怕的废话”。

想了想确实挺傻的,以后不乱写这种注释了。

本章批评的另一种观点是对注释的崇拜。最近@sofish在Twitter上说了他面试的时候也希望在代码中加上注释(大意),也许他觉得这是很尊重代码和以后的开发者的一种表现,但本书的观点是:

另外被批评的一种注释风格是:本应删除一句代码或者一大段代码的时候注释掉,希望后来人可以在遇到bug而回滚的时候发现这里而轻松回滚。这是@damao教我的一种注释风格,开始还觉得不错,不过本章认为这是版本控制的工作,想了想非常有道理。本应删除的代码而注释掉了,后来人会不敢删除掉这些注释,从而代码中出现了大量奇怪的注释。我真的亲眼见到过有大量这种注释的代码。

与此类似的一种风格是修改一句代码之后写上//edit by yuguo 2012.08.17 ,这也是版本控制的工作。

本章推崇的是简短而有意义的函数命名,尽量减少注释,承认“注释是为了弥补我们在用代码表达意图时遭遇的失败”。

当然也有一些注释是非常有意义的(但是要合理使用):

  • 警告,在文件头或者函数中注明非常重要的事情
  • todo,现代IDE能发现项目中所有的todo注释,要经常清理才有意义
  • 法律信息

最后,我想说的是,真实只在一处地方有:代码。所以尽管有时候我们也需要注释,但我们应该多花心思尽量减少注释量。

user

余果

https://yuguo.us

全栈工程师,《Web全栈工程师的自我修养》作者。