优雅的代码---浅谈注释的重要性

一、起因：

最近在写一些验收文档，在涉及一些设计文档的时候难免会去翻翻以前同事们一起的写的代码看看，假如你也和我一样有这种经历，

你是否感觉到了代码注释的重要性，今天，我就以下几方面谈谈自己对代码注释的一些简单看法，纯手打啊，欢迎大家吐槽！！！！

二、代码注释的重要性

其实代码注释的重要性我倒是觉得没必要在这过多的解释，我们只要回想一些情景就能知道其道理：

1、当你经过一段时间后，发现哪儿出问题或需要调整功能的时候；

2、当你去改别人代码的时候（你的代码也会被别人改）；

3、当你需要补一些设计文档的时候（比如现在的我）；

注：以上的这些情景紧发生在：1、你所面对的是别人的代码；2、如果你面对的是你的代码，再加一个前提，过一段时间之后。

三、项目中代码注释普遍存在的问题

1、忘记写注释：a、这种情况大多数是只写了方法本身功能注释，但是参数的含义并未加以说明(再遇到参数取名和本身含义更不符的情况下，就更头疼了)；b、有些就直接类和方法注释都没有（少数）

2、注释描述的不够清楚、太简单笼统话：一些类或方法注释太过于简单笼统，不能准确表达代码含义。

3、注释与本身代码所做的功能不符合：总结发生的情况可能有如下原因：a、写好一个方法或类，复制粘贴的时候把注释一起复制粘贴，完了后代码改了（代码有错误提示）忘了改注释（注释没有错误提示），导致注释与代码不符；b、一些方法参数，可能实现设计的时候没有，或者多设计了，后来经过反复修改，参数进行了调整，这时参数的注释还是以前初始版本，这种情况也是只注重代码，注释未得到及时的更新，导致注释与代码严重不符；

四、养成良好的代码注释习惯

从一开始进公司，我当时也对代码有过不好的对待，没把代码注释当回事，总是觉得先把代码功能实现了，至于注释后面再慢慢补。这种思想被池工及时纠正，真如池工所说，你经常写完代码还有多少次会回头再去补注释，确实如此。我们每个人都有惰性思想，所以在一些时候，该做的事一定不能省，不能等。

所以简单总结一些吧：

1、一定要养成良好的代码注释习惯，边写代码边注释，及时的记录下自己写代码过程中的思路；

2、一定要养成代码和注释同时对待，改完代码及时更正注释（代码是鱼，注释就是水，有了正确的注释，鱼才能更好的生存）；

3、多提升自己对代码的解释能力，用精炼的语言表达出代码的核心价值所在；

注：最后在说明一点吧，当然注释不是越多越好，弄得整个代码整篇都是注释，却很少看到代码，哈哈，这样就曲解注释的意思了，

必要的地方比如类、方法、参数是必须要注释的，至于方法体类的逻辑，选择性的加以注释就OK啦！比如一些不容易理解的if esle分支语句中，可以简单注释一下你逻辑。