关于阿里java开发规范中枚举类型字段必须有注释的思考

今天使用AlibabaJavaCodeGuidelines插件进行代码规范检查时，有一类关于枚举值注释的错误报了出来：

在阿里巴巴java开发规范中，是有下面这条规范
【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。

这条规范很好理解，一个枚举常量，如果没有注释的话，其含义只能通过命名去揣测，并不靠谱。

但是吧，当初我写代码的时候为什么没加注释呢？
原因也很简单，在我的系统设计中，将所有的异常，使用了枚举类，扩展了一个message属性，用于系统抛出异常后，给系统用户一个友好的提示，也就是对应的中文描述信息。

@Getter
public enum AppExceptionEnum implements ExceptionInterface {

    APP_CODE_OR_SECRET_ERROR("应用编码有误或密钥错误"),
    APP_CODE_NOT_EXIST("应用编码不存在"),
    ;
    private String message;

    AppExceptionEnum(String message) {
        this.message = message;
    }

}
1
2
3
4
5
6
7
8
9
10
11
12
13

这种情况下，这个枚举值什么含义，message属性中存放的中文描述足以表达清楚。
如果按照阿里java代码规范要求，则需要调整为以下方式：

@Getter
public enum AppExceptionEnum implements ExceptionInterface {

    /**
     * 应用编码有误或密钥错误
     */
    APP_CODE_OR_SECRET_ERROR("应用编码有误或密钥错误"),
    /**
     * 应用编码不存在
     */
    APP_CODE_NOT_EXIST("应用编码不存在"),
    ;
    private String message;

    AppExceptionEnum(String message) {
        this.message = message;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

这样就存在一个明显的问题，重复，注释与中文描述是重复的，新增的话，需要来两遍，修改的话，也要改两遍，并且需要同步，容易出现不一致的问题。

那么，这条规范是不是比较适合下面这种比较原始的枚举类，只有一个编码，没有进行扩展。

/**
 * 接口服务执行结果
 * @author wqliu
 */
@Getter
public enum ApiServiceExecuteResultEnum {

    /**
     * 成功
     */
    SUCCESS,
    /**
     * 错误
     */
    ERROR
    ;

}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

而对于我这种进行了扩展，有message属性来表达枚举常量含义的情况下，是不是不加注释更合理一些呢？

注：我们可以在枚举类上加上一句@SuppressWarnings(“AlibabaEnumConstantsMustHaveComment”)，这样进行代码规范检查的时候就不会再提示错误。

认真思考了下，还是遵循规范更优一些，主要是以下两方面：
1.如不加注释，在使用枚举值的地方，鼠标悬停并不会提示这个枚举值的含义，降低代码的可读性
2.对于重复问题，考虑到枚举值是常量，这些常量值的变动频率通常极低，新增和修改都比较少，重复两遍的问题，倒也可以接受

最后，回看了阿里规范的示例，也是重复了两遍。

   public enum TestEnum {
        /**
         * agree
         */
        agree("agree"),
        /**
         * reject
         */
        reject("reject");
        
        private String action;
    
        TestEnum(String action) {
            this.action = action;
        }
    
        public String getAction() {
            return action;
        }
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

最终的结论，这种情况下，遵循规范是最优的选择，即需要给枚举常量加注释。