个人对注释使用的总结

摘要: 在编程时注意方法或变量名命名的规范以及注释规则，养成一个良好的编程习惯，提高代码可读性。

个人对注释使用的总结：（参考：http://blog.csdn.net/shiyuezhong/article/details/8205281 作者:shiyuezhong）
Key：注释条件，注释类别，注释快捷键，注释规范（个人常用）
背景：模拟操作系统的课程设计的代码量算是我学习编程以来相对较多的，代码量大的同时，方法间的调用十分频繁，调用者也包括了好几个类（这跟项目结构有关系，一开始没有做好分析）。此之前不太重视注释的规范，看了队友的代码才发现，在IDE的帮助下，如果按照规定的注释规则，在使用到方法或者新建对象时，注释的内容可以在鼠标悬浮下显示，可以借注释提示自己定义的某个方法或者类的使用说明，参数说明等，省去回到类或者方法找注释的时间。当然，如果没有按照规则写注释，就只能手动回去找了。在团队合作中，如果使用不符合规范的注释，可能会让队友浪费很多不必要的时间。
正文：
合理地运用注释是团队开发合作的重要细节，它能提高代码的规范性和可读性，而且在IDE的帮助下，使用符合规则的注释可以方便自己开发时就地查看部分代码注释，同样的也方便了他人阅读代码。
代码注释要求注释形式统一，内容言简意赅，准确明了地表达注释意图。
注释条件（参考：http://blog.csdn.net/shiyuezhong/article/details/8205281 作者:shiyuezhong）
1、基本注释（必须加）
(a) 类（接口）的注释
(b) 构造函数的注释
(c) 方法的注释（持久化对象或VO对象的getter、setter方法不需加注释）
(d) 全局变量的注释
(e) 字段/属性的注释
2、特殊必加注释（必须加）
(a) 典型算法必须有注释。
(b) 在代码不明晰处必须有注释。
(c) 在代码修改处加上修改标识的注释。（*合作中使用队友代码尤其注意）
(d) 在循环和逻辑分支组成的代码中加注释。
(e) 为他人提供的接口必须加详细注释。

注释格式（参考：http://blog.csdn.net/shiyuezhong/article/details/8205281 作者:shiyuezhong）
1.单行(single-line)注释：“//……””/* ... */”
2.块(block)注释：“/*……*/”(块注释一般包含多行文本)
3.文档注释：“/**……*/” （文档注释可在鼠标悬浮时显示）
4. javadoc 注释标签语法
@author 对类的说明 标明开发该类模块的作者
@version 对类的说明 标明该类模块的版本
@see 对类、属性、方法的说明 参考转向，也就是相关主题
@param 对方法的说明 对方法中某参数的说明
@return 对方法的说明 对方法返回值的说明
@exception 对方法的说明 对方法可能抛出的异常进行说明

为了能显示文档注释，需要对于不同的情境使用特定的注释语法，使用相应的注释快捷键能提高效率。
1. 几种注释快捷键（Android Studio)
a.单行注释// ctrl+/
b.单行注释/**/ ctrl+shift+/
c.块注释 /*+回车
d.方法注释 /**+回车
2. 几种注释规范：
a.全局变量
/** 全局变量注释*/
private int TOTAL;

b.类（接口）注释（新建类时会在类头部自动生成注释模板内容）
/**
* 类描述
* Created by ${USER} on ${DATE}
*/
public class Foo {
}
注释模板设置（android studio)：File->Settings->IDE Settings->File and Code Templates -> include(Tab栏） ->选FileHeader

c.构造方法或普通方法的注释(在含有参数的方法(包括构造方法)上方 输入/**后回车会对参数进行注释)
public class Foo {
/**
* 对构造方法的描述
*/
public Foo(){
...
}
/**
* 对方法的描述
* @param a 对参数a的描述
*/
private void test(int a){
...
}
}

对于注释的使用，总结如下：
1. 单行注释用于描述普通变量（10字以内，尽量不要换行），
例 private String title;//不能超过120个中文字符
或者对某行代码进行解释
%^E%^*&(*&(*)*)(T^%$%^$% //只对逻辑不容易看懂代码的进行注释

2. 常量注释用/** 常量说明 */
例：/** CONSTANT是常量 */
private int CONSTANT;
3. 一般不对getter 和setter方法注释。
4. 注释的目的是帮助阅读代码。不要为了注释而注释。使用合理的命名方法可以帮助精简注释。