你会写注释吗？
前言
有一本书叫《代码整洁之道》，不知你看过没？
初次听闻此书，并未激发我的阅读欲。再次听闻，不免心想：代码竟还整洁之道？我倒要瞧瞧，怎么个整洁法。
我是怀着试探地心看了这本书，结果收获了满脑子糟糕的代码。天呐！这代码我貌似一句也看不懂，幸好还有文字，尚可宽慰我这颗被代码撞乱的心，于是咬咬牙读了下去。
这本书里面讲了很多代码整洁之道，关于有意义的命名、函数、注释、格式、错误处理、边界等共十七大篇章。如果你感兴趣，可以去看看。我只是粗略地看了一下，因为有些我也看不大明白。特别是当某些代码脱离了计算机而存在的时候，我好像不认识它们了，它们变得异常陌生。恕我我孤陋寡闻了，哎。
尽管如此，此书第四章中，关于“注释”的代码整洁之道，却给我留下了异常深刻的印象。Why? 因为里面关于注释的观点刷新了我的认知，与我的思想产生了一点点灵魂的碰撞，并且说服了我，还驱动我写下了这篇文章。
一、被注释吸引
下面是“注释”篇章的开头两段，特意贴了上来，因为我就是被这样的开头吸引了。希望它能带给你一点点启发。
不知你读完以上两段，作何感想？
我的感想是：如果你的代码写得足够优秀，是不需要过多注释的。注释最多可以证明糟糕的代码。
额，此刻我很想找一个捂脸的表情。与此同时，我在脑海里迅速地回忆了一遍注释之于我的心历路程：从最初知道“注释”这么个神奇玩意儿时的欣喜，到步步沦陷“注释”的魔爪，以致如今看着满屏的代码，不写点儿注释都感觉空落落的......
收回来，继续品。 作者开篇的观点约莫如下：
注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败
如果你发现自己需要写注释，再想想是否有办法翻盘，用代码来表达
注释会撒谎，代码在变动演化，但注释不能总是跟着走
只有代码是唯一准确的信息来源
注意，作者用来了“失败”一词。你无法找到表达自我的恰当方法，所以就要用注释，这并不值得庆祝。当然，这并不意味作者就完全否定了注释的价值，程序员应当负责将代码保持在可维护、有关联、精确的高度。只不过作者更倾向于把力气用在写清楚代码上，直接保证无须编写注释，或者花心思减少注释量。
二、好的注释
有些注释是必须的，作者列举了一些值得写的注释。
公司代码规范要求编写与法律有关的注释
提供基本信息的注释
对意图的解释
阐释：把晦涩难明的参数或返回值的意义翻译为某种可读形式
警示：用于警告其他程序员会出现某种后果的注释
TODO 注释：是一种程序员认为应该做，但由于某些原因目前还没做的工作
放大：放大某种看起来不合理之物的重要性的注释
公共 API 中的 Javadoc
尽管如此，作者一再强调：唯一真正好的注释是你想办法不去写的注释。足见作者对注释之深恶痛疾，对糟糕代码之嫌弃，对代码整洁要求之高。你可以细品。
三、坏的注释
果然是有代码洁癖的人，作者用了更多的篇幅来描述坏的注释。
喃喃自语：因为过程需要就添加注释，就是无谓之举
多余的注释：并不比代码本身提供更多的信息，甚至比读代码所花时间长
误导性注释：写出不够精确的注释误导读者
循规式注释：每个函数都要有 Javadoc 或每个变量都要有注释的规则愚不可及
日志式注释：每次编辑代码时，在模块开始处添加一条注释，应当全部删除
废话注释：喋喋不休，废话连篇的注释，一旦代码修改，将变成一堆谎言
能用函数或变量时就别用注释：建议重构代码，删掉注释
位置标记：在源代码中标记某个特别位置，多数实属无理又鸡零狗碎
括号后面的注释：如果你发现自己想标记右括号，其实应该做的是缩短函数
归属与署名：源代码控制系统是这类信息最好的归属地
注释掉的代码：注释掉的代码堆积在一起，就像酒瓶底的渣滓一般
HTML 注释：源代码注释中的 HTML 标记是一种厌物
非本地信息：假如你一定要写注释，请确保它描述了离它最近的代码
信息过多：别在注释中添加有趣的历史性话题或无关的细节描述
不明显的关系：注释及其描述的代码之间的联系应该显而易见
函数头：短函数不需要太多的描述，选个好的函数名胜于写函数头注释
一言以蔽之：用整理代码的决心替代创造废话的冲动吧。 你会发现自己成为更优秀、更快乐的程序员。
小结
作者把“注释”拎出来，说了这么多，最终还是回归到了代码本身。
那如何才能写出整洁的代码呢？如果你不明白整洁对代码的意义，尝试去写整洁代码就毫无意义。如果你明白糟糕的代码给你带来的代价，你就会明白，花时间保持代码整洁不但有关效率，还有关生存。争取让营地比你来时更干净吧！
最后，贴上书中震撼我的一隅，希望它能指引你逐渐走向代码整洁之道，与君共勉！
作者：linwanxia
来源：https://juejin.cn/post/7083029096615116837
