《码处高效：Java开发手册》之代码风格

流水淡，碧天长，鸿雁成行。编码风格，简捷清爽，反引无限风光。

在美剧《硅谷》中有这样一个经典镜头，主人公 Richard 与同为开发工程师的女友闹分手，理由是两人对缩进方式有着截然不同的编程习惯，互相鄙视对方的代码风格。Richard 认为＂ one tab saves four spaces “，缩进使用 Tab 键操作更快，更节省存 储空间，而女友坚持使用空格缩进，连续四次敲击空格的声音，把 Richard 折磨到几近崩溃，认为这是种精神折磨。 Richard 觉得难以相处，吵完架下楼梯时，不小心摔倒了 还淡定地说，”I just tried to go down the stairs four steps at a time ” （这只是表达我的立场而已）。Tab 键和空恪键的争议在现实编程中确实存在。除此之外，在其他代码风格上，也存在不同的处理方式，往往是谁也说服不了谁，都站在自身”完全正确”的立场上，试图说服对方。这在团队开发效率上，往往是一个巨大的内耗，无休止的争论与最后的收益是成反比的。所以我们认为一致性很重要，就像交通规则一样，我国规定靠右行驶，有些国家则规定靠左行驶，并没有绝对的优劣之分，但是在同一个国家或地区内必须要有统一的标准。代码风格也是如此，无论选择哪一种处理方式，都需要部分人牺牲小我，成就大我，切实提升团队的研发效能。

代码风格并不影响程序运行，没有潜在的故障风险，通常与数据结构、逻辑表达无关，是指不可见字符的展示方式、代码元素的命名方式和代码注释风格等。比如，大括号是否换行、缩进方式、常量与变量的命名方式、注释是否统一放置在代码上方等。代码风格的主要诉求是清爽统一、便于阅读和维护。统一的代码风格可以让开发工程师们没有严重的代码心理壁垒，每个人都可以轻松地阅读并快速理解代码逻辑，便于高效协作，逐步形成团队的代码”味道”。

命名规约

代码元素包括类、方法、参数、常量、变量等程序中的各种要素。合适的命名，可以体现出元素的特征、职责 ，以及元素之间的差异性和协同性。为了统一代码风格，元素的命名要遵守以下约定。

​ 什么是常量？常量是在作用域内保持不变的值， 一般用 final 关键字进行修饰，根据作用域区分，分为全局常量、类内常量、局部常量。全局常量是指类的公开静态属性 使用 public static final 修饰；类内常量是私有静态属性，使用 private static final 修饰，局部常量分为方法常量和参数常量，前者是在方法或代码块内定义的常量，后者是在定义形式参数时 增加 final 表示此参数值不能被修改。全局常量和类内常量是最主要的常量表现形式，它们的命名方式比较特殊，采用字母全部大写、单词之间加下画线的方式。而局部常量采用小驼峰形式即可。示例代码如下：

public class Constant {
    public static final String GLOBAL CONSTANT = "shared in global";
    private static final String CLASS CONSTANT = "shared in class";

    public void f(String a) {
        final String methodConstant = "shared in method";
    }

    public void g( final int b) {
        // 编译出错，不允许对常量参数进行重新赋值
        b = 3;
    }
}

​ 常量在代码中具有穿透性，使用甚广。如果没有一个恰当的命名，就会给代码阅读带来沉重的负担，甚至影响对主干逻辑的理解。首当其冲的问题就是到处使用魔法值。魔法值即”共识层面”上的常量，直接以具体的数值或者字符出现在代码中。这些不知所云的魔法值极大地影响了代码的可读性和可维护性。下面先来看一段实际业务代码。

public void getOnlinePackageCourse(Long packageId, Long userId) {
    if (packageId == 3) {
        logger.error("线下课程，无法在线观看");
        return;
    }
    // 其它逻辑处理
    PackageCourse online = packageService.getByTeacherId(userId);
    if (online.getPackageId() == 2) {
        logger.error("未审核课程");
        return;
    }
    // 其他逻将处理
}

​ 以上示例代码中，信手拈来的2和3分别表示未审核课程和线下课程，仅仅是两个数字，似乎很容易记忆。但事实上除2和3两种状态外，还有1、4、5分别代表新建、审核未通过、审核通过。在团队规模较小时，口口相传，倒也勉强能够记住这五个数字的含义，早期还有零星的注释，驾轻就熟的情况下，连注释也省了。现实是残酷的，团队迅速扩大后，课程状态个数也在逐步增加，新来的开发工程师在上线新功能模块时，把”审核通过”和”未审核课程”对应的数字搞反了，使得课程展示错误，导致用户大量投诉。随着应用变得越来越复杂，这些魔法值几乎成了整个后台服务代码中的梦魔。团队架构师终于下定决心进行系统重构，把这些魔法值以合适的命名方式定义成全局常量。使用 Enum 枚举类来定义课程类型，示例代码如下：

public enum CourseTypeEnurn {
    /**
     * 允许官方和讲师创建和运营
     */
    VIDEO_COURSE(l, "录插课程"),
    /**
     * 只允许官方创建和运营，初始化必须设置合理的报名人数上限
     */
    LIVE_COURSE(2, "直播课程"）,
    /**
     * 只允许官方创建和运营
     */
    OFFLINE_COURSE(3，"线下课程");

    private int seq;
    private String desc ;

    CourseTypeEnurn (int seq, String desc) {
        this.seq = seq;
        this. desc = desc ;
    }

    public int getSeq() {
        return seq;
    }

    public String getDesc() {
        return desc;
    }
}

​ 上述示例代码把课程类型分成三种：录播课程、直播课程、线下课程。枚举类型几乎是固定不变的全局常量，使用频率高、范围广，所以枚举常量都需要添加清晰的注释，比如业务相关信息或注意事项等。再把课程状态分为新课程、未审核课程、审核通过、审核未通过、已删除五种状态。考虑到后续课程状态还会再追加，并且状态没有扩展信息，所以用不能实例化的抽象类的全局常量来表示课程状态，示例代码如

public abstract class BaseCourseState {
    public static final int NEW_COURSE = 1;
    public static final int UNAUTHED_COURSE = 2;
    public static final int PASSED_COURSE = 3;
    public static final int NOT_PASSED_COURSE = 4;
    public static final int DELETED_COURSE = 5;
}

使用重构后的常量修改原有的魔法值，对比一下代码的可读性

public void getOnlinePackageCourse(Long packageId, Long userId) {
    if (packageId == CourseTypeEnum.OFFLINE_COURSE.getSeq()) {
        logger.error("线下课程，无法在线观看");
        return;
    }
    // 其它逻辑处理
    VideoCourse course = packageService.getByTeacherId(userId);
    if (course.getState() == BaseCourseState.UNAUTHED_COURSE) {
        logger.error("未审核课程");
        return;
    }
    // 其他逻将处理
}

​ 我们认为，系统成长到某个阶段后，重构是种必然选择。优秀的架构设计不是去阻止未来切重构的可能性，毕竟技术枝、业务方向和规模都在不断变化，而是尽可能让重构来得晚一些，重构幅度小一些。即使类内常量和局部常量当前只使用一次，也需要赋予一个有意义的名称，目的有两个：第一、望文知义，方便理解 第二、后期多次使用时能够保证值出同源。因此，无论如何都不允许任何魔法值直接出现在代码中，避免魔法值随意使用导致取值不一致，特别是对于字符串常量来说，应避免没有预先定义，就直接使用魔法值。所谓常 在河边走，哪有不湿鞋，在反复的复制与粘贴后，难免会出现问题，警示代码如下：

String key = "Id#taobao_" + tradeId;
cache.put(key, value);

​ 上述代码是保存信息到缓存中的方法，即使用魔法值组装 Key。这就导致各个调用方到处复制和粘贴字符串 Id#taobao_ 这样似乎很合理。但某一天，某个粗心的程序员把Id#taobao_ 复制成为Id#taobao，少了下画线。这个错误在测试过程中，并不容易被发现 因为没有命中缓存，会自动访问数据库。但在大促时，数据库压力急剧上升，进而发现缓存全部失效，导致连接占满，查询变慢。小处不小，再次说明魔法值害人害己。

​ 某些公认的字面常量是不需要预先定义的，如 for( int i=0; … ）这里的0是可以直接使用的。true和 false也可以直接使用，但是如果具备了特殊的含义，就必须定义出有意义的常量名称，比如在 TreeMap 源码中，表示红黑树节点颜色的 true 和 false 就被定义成为类内常量，以方便理解∶

private static final boolean RED = false;
private static final boolean BLACK = true;

​ 常量命名应该全部大写，单词间用下画线隔开，力求语义表达完整清楚，不要嫌名字长，比如，把最大库存数量命名为 MAX_STOCK_COUNT，把缓存失效时间命名为 CACHE_EXPIRED TIME。

​ 什么是变量从广义来说，在程序中变量是一切通过分配内存并赋值的量，分为不可变量（常量）和可变变量。从狭义来说，变量仅指在程序运行过程中可以改变其值的量，包括成员变量和局部可变变量等。

​ 一般情况下，变量的命名需要满足小驼峰格式，命名体现业务含义即可。存在一种特殊情况，在定义类成员变量时，特别是在 POJO类中，针对布尔类型的变量，命名不要加 is 前缀，否则部分框架解析会引起序列化错误。例如，定义标识是否删除的成员变量为 Boolean isDeleted，它的 getter 方法也是 isDeleted()，框架在反向解析的时候，”误以为”对应的属性名称是 deleted，导致获取不到属性，进而抛出异常。但是在数据库建表中，推荐表达是与否的值采用 is_xxx 的命名方式，针对此种情况，需要在

代码展示风格

缩进、空格与空行造就了代码的层次性和规律性，有助于直观、快速、准确地理解业务逻辑。没有缩进、空格和空行的代码可读性极差。如下反例所示∶

table=newTab;
if (oldTab!=null){ for(int j=0;j=0){
for(int i=0;i

代码中需要限定每行的字符个数，以便适配显示器的宽度，以及方便CodeReview时进行 diff 比对。对于无节制的行数字符，需要不断地拉取左右滚动条或者键盘移动光标，那是多么差的体验。因此，约定单行字符数不超过120个，超出则需要换行，换行时遵循如下原则∶
（1）第二行相对第一行缩进4个空格，从第三行开始，不再继续缩进，参考示例。

（2）运算符与下文一起换行。

（3）方法调用的点符号与下文一起换行。

（4）方法调用中的多个参数需要换行时，在逗号后换行。

（5）在括号前不要换行。

StringBuffer sb = new StringBuffer();
// 超过120个字符的情况下，换行缩进 4个空格，并且方法前的点号一起换行
sb.append ("ma").append("chu")...

    .append ("gao")...

    .append ("xiao")...

    .append("yealh");

代码注释

注释是一个看起来简单，容易被忽视，但是作用又不容小觑的话题。好的注释能起到指路明灯、拨云见日、警示等作用，具体包括∶能够准确反映设计思想和代码逻辑;能够描述业务含义，使其他工程师能迅速了解背景知识。与代码不同，注释没有语法的限制，完全取决于编写者的能力和发挥，但这并不意味着注释可以天马行空。书写注释要满足优雅注释三要素。

注释格式主要分为两种∶ 一种是 Javadoc 规范，另一种是简单注释。

​ 类、类属性和类方法的注释必须遵循Javadoc规范，使用文档注释（/***/）的格式。按 Javadoc 规范编写的注释，可以生成规范的 JavaAPI 文档，为外部用户提供非常有效的文档支持。而且在使用IDE 工具编码时，IDE 会自动提示所用到的类、方法等注释，提高了编码的效率。

​ 这里要特别强调对枚举的注释是必需的。有人觉得枚举通常带了String name 属性，已经简要地说明了这个枚举属性值的意思，此时注释是多余的。其实不然，因为∶

​ （1）枚举实在太特殊了。它的代码极为稳定。如果它的定义和使用出现错误，通常影响较大。

​ （2）注释的内容不仅限于解释属性值的含义，还可以包括注意事项、业务逻辑。如果在原有枚举类上新增或修改一个属性值，还需要加上创建和修改时间，让使用者零成本地知道这个枚举类的所有意图。

​ （3）枚举类的删除或者修改都存在很大的风险。不可直接删除过时属性，需要标注为过时，同时注释说明过时的逻辑考虑和业务背景。

​ 包括单行注释和多行注释。特别强调此类注释不允许写在代码后方，必须写在代码上方，这是为了避免注释的参差不齐，导致代码版式混乱。双画线注释往往使用在方法内部，此时的注释是提供给程序开发者、维护者和关注方法细节的调用者查看的。因此，注释的作用更应该是画龙点睛的，通常添加在非常必要的地方，例如复杂算法或需要警示的特殊业务场景等。

说明：本文内容参考《码出高效：Java开发手册》第三章 代码风格，有兴趣的读者可以看书的原文。

Original: https://www.cnblogs.com/reminis/p/16120110.html
Author: 小懒编程日记
Title: 《码处高效：Java开发手册》之代码风格