序言

晚上我坐在马桶上，不知为何脑子闪过一个关于代码注释的问题：写代码应该追求代码的自注释还是开发自己写注释？刚开始工作的时候，看了很多关于代码规范的文档或书籍，把上面的言论奉为金科玉律，深信不疑，可是经过几年的工作，我并不认同了。

书本上的理论

以前的笔记里还记着这些理论呢。

《重构-改善既有代码的设计》：

任何一个傻瓜都能写出计算机可以理解的代码，唯有写出人类容易理解的代码，才是优秀的程序员。

《代码整洁之道》上的言论：

什么是整洁的代码？

1.我喜欢优雅和高效的代码。代码逻辑应当直截了当，令缺陷难以隐藏；尽量减少依赖关系，使之便于维护；依据某种分层战略完善错误处理代码；性能调至最优，省得引诱别人做没规矩的优化，搞出一些混乱来。整洁的代码只做好一件事。

2.整洁的代码简单直接。整洁的代码如同优美的散文。整洁的代码从不隐藏设计者的意图，充满了干净利落的抽象和直截了当的控制语句。

3.整洁的代码总是看起来像是某位特别在意它的人写的。几乎没有改进的余地。

4.如果每个例程都让你感到深合己意，那就是整洁代码。如果代码让编程语言看起来是专为解决那个问题而存在的，就可以称之为漂亮的代码。

有意义的命名：

变量、函数或类的名称应该已经答复了所有的大问题。它该告诉你，它为什么存在、它做什么事、应该怎么用。如果名称需要用注释来补充，那就不算是名副其实。

以前看这些东西看的是津津有味，觉得说的很对。包括以前的公司也宣传这种规范，说起变量名之前要思考一下，尽量少些注释。

国内的实际情况

关于前面提到的书籍上的规范性理论，我的体会是：这些书都是外国人写的，编程语言是他们发明的，他们的母语也是英语，所以他们在写代码的时候追求代码的强语义性的收益很高，不管用啥单词他们一看就懂，再考虑下命名与业务的契合度就很完美，他们看代码那真就像看”散文“一样了。

但是国内的实际情况是什么，开发人员写代码碰到不知道怎么命名的单词都是随手翻译一下就写上去了，不管这单词认不认识或者生僻与否，还有很多拼写错误也不纠正，再加上代码逻辑不够清晰的话，那给人的阅读体验当然不好，那什么“山”就来了。

再说说有些公司为什么提倡不写注释，要用命名体现意图。这些都是老一辈程序员有情怀，且带的都是小团队，而且业务语言和开发语言都比较统一，所以代码名字写准确了，基本就能很好的理解业务。但是大公司就不行了，一个组十几个人，时间紧任务重，有些领导甚至没时间review代码，或者根本不在乎你写的啥，功能实现就行了，所以也没人在乎这些规范了。加上张三的任务李四也不一定了解，再不写点注释那接手的人痛苦至极。

总结

所以，必要时要尽量多写的代码注释，把逻辑描述清楚，利己利人。当然这并不意味着可以随便命名了。注释要能帮助梳理整体逻辑，必要的不能省，不能自我感觉良好，看着自己的干净的代码心里美滋滋，也许很快就忘了。非必要时就不要写注释了，有的人可能待过特殊的公司，每一行代码都写注释，像什么list.get(0)，true或者false都写个注释，那也实在没必要。

最后，我觉得阿里开发手册里关于注释规范说的挺好，贴一下：

1. 【参考】对于注释的要求：第一、能够准确反映设计思想和代码逻辑；第二、能够描述业务含 义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同 天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看 的，使其能够快速接替自己的工作。

2. 【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一 个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释又是相当大的负担。