前段时间我准备开源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注释，要经常清理才有意义
• 法律信息

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