【Java编程规范】注释篇

注释的哲学︰注释里尽量写为什么,而不是做了什么。是用来解释不为人知的corner case。

包注解

包注解在工作中往往比较特殊,通过包注解可以快速知悉当前包下代码是用来实现哪些功能,强烈建议工作中加上,尤其是对于一些比较复杂的包,包注解一般在包的根目录下,名称统一为package-info.java

1
2
3
4
5
6
7
8
9
10
 * 落地也质量检测
* 1. 用来解决什么问题
* 对广告主投放的广告落地页进行性能检测,模拟不同的系统,如Android,IOS等;
*
* 2. 如何实现
* 基于chrome浏览器,用chromedriver驱动浏览器,设置对应的网络,OS参数,获取到浏览器返回结果。
*
* @author cruder
*/
package cn.mycookies.landingpagecheck;

枚举注释

  • 枚举类的各个属性值都要使用注解,枚举可以理解为是常量,通常不会发生改变,通常会被在多个地方引用,对枚举的修改和添加属性通常会带来很大的影响。

方法注释

  • 在每个方法前面必须加上方法注释,对于方法中的每个参数,以及返回值都要有说明。

属性注解

  • 在每个属性前面必须加上属性注释,通常有一下两种形式,至于怎么选择,你高兴就好,不过一个项目中要保持统一。

类注接

  • javadoc注解中,每个类都必须有注解。

  • 如果一个方法重写了超类中的方法,那么Javadoc并非必需的。

其他

  • 保持排版整洁,不要使用行尾注释;
  • 双斜杠和星号之后要用1个空格分隔。
    int id = 1;// 反例:不要使用行尾注释
    //反例:换行符与注释之间没有缩进
    int age = 18;
    // 正例:姓名
    String name;
  • 特殊注释标记,请注明标记人与标记时间。注意及时处理这些标记,通过标记扫描,经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。

    1) 待办事宜(TODO):( 标记人,标记时间,[预计处理时间]) 表示需要实现,但目前还未实现的功能。这实际上是一个Javadoc的标签,目前的Javadoc还没有实现,但已经被广泛使用。只能应用于类,接口和方法(因为它是一个Javadoc标签)。

    2) 错误,不能工作(FIXME):(标记人,标记时间,[预计处理时间]) 在注释中用FIXME标记某代码是错误的,而且不能工作,需要及时纠正的情况。