一、注解的原则
优雅的注解通常要满足三要素。
- Nothing is strange
没有注解的代码对于阅读者非常不友好，哪怕代码写的在清除，阅读者至少从心理上会有抵触，更何况代码中往往有许多复杂的逻辑，所以一定要写注解，不仅要记录代码的逻辑，还有说清楚修改的逻辑。 - Less is more
从代码维护角度来讲，代码中的注解一定是精华中的精华。合理清晰的命名能让代码易于理解，对于逻辑简单且命名规范，能够清楚表达代码功能的代码不需要注解。滥用注解会增加额外的负担，更何况大部分都是废话。1 2
// 根据id获取信息【废话注解】 getMessageById(id)
- Advance with the time
注解应该随着代码的变动而改变，注解表达的信息要与代码中完全一致。通常情况下修改代码后一定要修改注解。
二、注解格式
注解大体上可以分为两种，一种是javadoc注解，另一种是简单注解。javadoc注解可以生成JavaAPI为外部用户提供有效的支持javadoc注解通常在使用IDEA，或者Eclipse等开发工具时都可以自动生成，也支持自定义的注解模板，仅需要对对应的字段进行解释。参与同一项目开发的同学，尽量设置成相同的注解模板。
2.1 包注解
包注解在工作中往往比较特殊，通过包注解可以快速知悉当前包下代码是用来实现哪些功能，强烈建议工作中加上，尤其是对于一些比较复杂的包，包注解一般在包的根目录下，名称统一为package-info.java。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/**
* 落地质量检测
* 1. 用来解决什么问题
* 对广告主投放的广告落地页进行性能检测，模拟不同的系统，如Android，IOS等;
* 模拟不同的网络：2G，3G，4G，wifi等
*
* 2. 如何实现
* 基于chrome浏览器，用chromedriver驱动浏览器，设置对应的网络，
* OS参数，获取到浏览器返回结果。
*
* 注意： 网络环境配置信息{@link cn.mycookies.landingpagecheck.meta.NetWorkSpeedEnum}
* 目前使用是常规速度，可以根据实际情况进行调整
*
* @author cruder
* @time 2019/12/7 20:3 下午
*/
package cn.mycookies.landingpagecheck;
2.2 类注接
javadoc注解中，每个类都必须有注解。
1
2
3
4
5
6
7
8
9
/**
* Copyright (C), 2019-2020, Jann balabala...
*
* 类的介绍：这是一个用来做什么事情的类，有哪些功能，用到的技术.....
*
* @author 类创建者姓名 保持对齐
* @date 创建日期 保持对齐
* @version 版本号 保持对齐
*/
2.3 属性注解
在每个属性前面必须加上属性注释，通常有一下两种形式，至于怎么选择，你高兴就好，不过一个项目中要保持统一。
1
2
3
4
5
6
7
/** 提示信息 */
private String userName;
/**
* 密码
*/
private String password;
2.4 方法注释
在每个方法前面必须加上方法注释，对于方法中的每个参数，以及返回值都要有说明。
1
2
3
4
5
6
7
/**
* 方法的详细说明，能干嘛，怎么实现的，注意事项...
*
* @param xxx 参数1的使用说明， 能否为null
* @return 返回结果的说明， 不同情况下会返回怎样的结果
* @throws 异常类型 注明从此类方法中抛出异常的说明
*/
2.5 构造方法注释
在每个构造方法前面必须加上注释，注释模板如下：
1
2
3
4
5
6
/**
* 构造方法的详细说明
*
* @param xxx 参数1的使用说明， 能否为null
* @throws 异常类型 注明从此类方法中抛出异常的说明
*/
三、注意事项
在使用注解时应该注意一下几点：
- 枚举类的各个属性值都要使用注解，枚举可以理解为是常量，通常不会发生改变，通常会被在多个地方引用，对枚举的修改和添加属性通常会带来很大的影响。
- 保持排版整洁，不要使用行尾注释；双斜杠和星号之后要用1个空格分隔。
1
2
3
4
5
6
7
8
9
10
11
int id = 1;// 反例：不要使用行尾注释
//反例：换行符与注释之间没有缩进
int age = 18;
// 正例：姓名
String name;
/**
* 1. 多行注释
*
* 2. 对于不同的逻辑说明，可以用空行分隔
*/