避免注释
source link: https://yuguo.us/weblog/avoid-comments/
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
Introduction
余果 2012-08-17 back-end
前段时间我准备开源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注释，要经常清理才有意义
最后，我想说的是，真实只在一处地方有：代码。所以尽管有时候我们也需要注释，但我们应该多花心思尽量减少注释量。
我写字的地方迁移到公众号啦~欢迎关注我的公众号：余果专栏
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK