我的注释等级

我一直在想两个比较有争议的问题——一段拥有良好功能和效率的代码，是不是一定有很好的注释？反之，拥有良好注释的代码，是不是一定有很好的功能和效率呢？

 

有点无聊的问题，因为两个问题的答案都不是百分百绝对的，的确如此，但其中却多少有迹可循。

 

前一个问题，我觉得可以这样进行佐证：一段代码，有很好的效率和功能，但却没有注释或者注释很糟糕，那结果是什么呢？结果是这段代码所达到的效果很可能不是最好的。特例情况只有开发者很聪明，超出凡人很多。

 

后一个问题：一段拥有良好注释的代码，很可能拥有很好的功能和效率。特例情况只有很笨，低出凡人很多。而且，这种特例出现的情况要远远低于前一个问题中聪明人出现的概率。

 

原因是什么呢？原因是，良好的注释，让人一目了然的注释在某些程度上说，可以说是开发者在编写代码时思路的写照，如果开发者的思路很清晰，那他的代码必然很清晰，如同一幅很好的山水画，一片很美的文章，有段落，有层次，自然也会附带上必要的说明，这说明就是注释。相反，如果规范不到位，注释不到位，即便功能很强大，那也只能说，代码是想到哪写到哪，很难说那是一个整体的构想，一个系统规划后实现的功能。

 

不要急着反驳我，你反驳我，我会认为你很聪明、或者很笨。

 

注释的确没实现任何功能，很多开发者也认为那玩意儿没什么用，但在我看来它却是必不可少的。注释就好比一样复杂的电子产品的使用说明书，有它没它东西都一样用，但少了说明书，使用者必然会多走不少弯路。

 

自从大学毕业之后，我走了不少弯路，也看着别人走了很多弯路，自己的感慨自然很多。然后感着感着，在我心里就把我所见过的“产品说明书”划分了一个等级：

 

五级：没有注释，或者仅有“// TO DO”开发工具自动生成的东西。

 

和注释一样，代码也是一团糟，没有缩进，没有注释，变量也是乱七八糟，只要是需要的东西，都堆叠到一起。无论从那个角度看都是一团没法维护的东西。这样的代码，初学者看不懂，元老们也看不懂，三五个月之后原创者也看不懂。我觉得，在我心中就是最次的一级，如果有人出版一本转讲代码规约的书，处在五级的代码完全可以作为反面教材。

 

在我心里，这是最次的一种状态。

 

四级：有少量注释。

 

有少量注释的情况是由于开发者有点懒惰造成的，他会认为一些东西没必要注释，就省略掉了，或者干脆是因为开发者认为注释没用，就省略掉了一部分注释造成的。但这样的代码，缺少的只是部分注释，代码的缩进、换行等规范都做的不错，至少看得过去。

 

三级：过度注释。

 

过度注释的情况和之前的“少量注释”正好相反，代码整洁的要命要命的，而且开发者还十分勤快，把for循环中的continue，return之类地球人都知道的东西都写上注释。可以说这样的代码很好看，整体的效果会非常好，也很明了，但不实用，因为几个月之后任何人在看这段代码的时候，原本只看见一个return就知道是返回值，反倒要多花一秒时间去看它脑袋上的注释。有画蛇添足的嫌疑。

 

二级：注释完整，适度。

 

代码整洁有序，注释有张有弛。不必完全遵循有些对日开发那种两行一注释，缩进空行都是bug的状态，但注释出现在他们需要的地方，空行也出现在他们应该出现的地方，让人看了很容易划分出段落，以及对应的作用是什么。

 

个人觉得，到这里已经很好了。

 

一级：MAGIC.

 

到了这里,我觉得除了MAGIC实在没什么能形容的了。俗话说物极必反，代码也是如此。这种代码和五级的状态基本一致，也是没有注释，但不会有“// TO DO”开发工具自动生成的东西存在。

之所以没有注释，因为代码编写者的思路和能力都已经到了一个十分可怕的地步，让每一个方法，每一行代码都做到了自解。

每一个函数、每一个方法都不会过长，而且每一行代码也都不会由过多字符组成，每一行代码都在实现一个功能，一个让人一眼看去就知道意思的功能。这样的代码读起来就好象是在看一篇语言十分凝练的散文，字字珠玑，而且言达其意，又何必需要注释呢？而代码本身，也就是注释。

 

可惜，我只知道有这样的代码存在，它叫“自解代码”，可我写不出来，也很难形容出来，只能说它是MAGIC.

 

等级分完了，也许和你心中的标准不一样，但没关系，未必我的就是正确的， 这也不过是我一个人的臆想而已。

 

博文写完了，多说一句实话，其实我的状态也只比“三级”好了那么一点点！