注释的哲学︰注释里尽量写为什么,而不是做了什么。是用来解释不为人知的corner case。
包注解
包注解在工作中往往比较特殊,通过包注解可以快速知悉当前包下代码是用来实现哪些功能,强烈建议工作中加上,尤其是对于一些比较复杂的包,包注解一般在包的根目录下,名称统一为package-info.java
1 | * 落地也质量检测 |
枚举注释
- 枚举类的各个属性值都要使用注解,枚举可以理解为是常量,通常不会发生改变,通常会被在多个地方引用,对枚举的修改和添加属性通常会带来很大的影响。
方法注释
- 在每个方法前面必须加上方法注释,对于方法中的每个参数,以及返回值都要有说明。
属性注解
- 在每个属性前面必须加上属性注释,通常有一下两种形式,至于怎么选择,你高兴就好,不过一个项目中要保持统一。
类注接
javadoc注解中,每个类都必须有注解。
如果一个方法重写了超类中的方法,那么Javadoc并非必需的。
其他
- 保持排版整洁,不要使用行尾注释;
- 双斜杠和星号之后要用1个空格分隔。
int id = 1;// 反例:不要使用行尾注释
//反例:换行符与注释之间没有缩进
int age = 18;
// 正例:姓名
String name; - 特殊注释标记,请注明标记人与标记时间。注意及时处理这些标记,通过标记扫描,经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
1) 待办事宜(TODO):( 标记人,标记时间,[预计处理时间]) 表示需要实现,但目前还未实现的功能。这实际上是一个Javadoc的标签,目前的Javadoc还没有实现,但已经被广泛使用。只能应用于类,接口和方法(因为它是一个Javadoc标签)。
2) 错误,不能工作(FIXME):(标记人,标记时间,[预计处理时间]) 在注释中用FIXME标记某代码是错误的,而且不能工作,需要及时纠正的情况。