整洁代码--写好注释

写在标题前：看了很多资料说“写注释是为了弥补代码表达意图时的失败”，的确有道理，好的代码确实是不太需要注释的，但这种情况目前我只感觉是存在于理想中，现实中，尤其是国内，注释还是很重要的，注释写的清楚，能为阅读你代码的人提供很大的帮助，尤其是无法保证代码作者和阅读者英文水平不对等的情况下，中文注释显得尤为重要。千万弄明白注释与代码的关系：是画龙点睛、不是越俎代庖更不是画蛇添足！

1.不要花过多的时间维护注释，而是要去优化你的代码

如果你发现你的大量代码需要用注释进行描述，那你应该先修改好代码，好的代码需要少量点睛的注释，而不是靠大篇幅的注释进行描述。优化你的代码名称，代码结构最为重要！
           

2.应该添加的注释

2.1 法律信息

有时，我们的公司代码规范要求编写与法律相关的注释，在编写这类注释时，尽量指向一份标准的外部文档，而不是把条款全写在注释里。
           

2.2 对意图的注释

比如解释一下pojo类，以及一段正则表达式是做什么的，再或者是业务逻辑解释。这是最常用的注释。尽量写的言简意赅。
           

2.3 代码不可修改时的描述

在团队作业的情况下，肯定会遇到其他人写的代码，以及固定代码库，这类代码往往我们不能进行修改，所以如果觉得这些代码描述的不够清楚，为了将来方便自己理解，可以在此类代码中加入注释。
           

2.4 警示类注释

这类注释用于警告自己或其他程序员会出现某种后果。
           

2.5 TODO 注释

TODO 注释是一个程序员认为应该做的，但是由于某些原因目前还没做的工作。比如你需要写一个很长的业务逻辑判断时，但发现你还有5分钟就下班了，你就应该在这段业务逻辑上写上TODO类型注释，并在第二天完成它。
           

2.6 编写公共API时

良好的注释，以及说明会令使用者感激不尽。
           

3. 不好的注释

3.1 不知所云的注释

此类注释不是说作者不知所云，而是代码阅读者在没有上下语境的情况下看到这个注释完全不知道是在干什么，或者需要阅读很大很长一段代码之后才能理解。
           

3.2 多余的注释

此类注释描述的信息往往是应该由代码所表述的，再或者代码已经清楚的描述出来，而纯粹的复述性多余。
           

3.3 误导性注释

对于返回结果的描述，或者对于0代表什么1代表什么这类的描述，一定要准确，描述不清的注解写了还不如不写。
           

3.4 规矩性注释

例如每个函数都要有注释，即使这个注释并没有什么用，这种注释就不要写了，这就是多余的注释。
           

3.5 日志式注释

比如这段代码的修改者，修改时间，修改内容等。现在svn 等工具已经很方便了，这类注释应该淘汰了。
不过我还是在使用这种注释，可能我目前的工作环境适合这种，人不多的小组，当看到不明白的代码时，看到这是谁修改的或编写的，直接问就好了，但是大公司大项目可能不适合。因人而异吧。
           

3.6 括号后面的注释

比如有一个很长的try catch ，有时会在}后面加上//try  方便找到try的结尾，其实这时候可以考虑重构缩短函数了。 
           

3.7 代码注释

注释掉代码这在编程中很正常不过了，但一定要给注释掉的代码及时处理，没有的代码就删除掉，如果觉得将来可能会用到那么请在注释中写明为什么而注释，因为随着时间的积累，越来越多的注释代码插在代码中，后续的程序员根本不敢删除它，却又不明白这一坨都是什么。
           

本文为阅读书籍、向资深程序员请教、以及自身摸索得出，如遇版权，请及时联系。

欢迎转载，但希望注明出处，谢谢。