核心原则先让错误提前暴露、减少人脑上下文负担、降低阅读时的推理成本分为 6 大类【分支与判断优化】【注释 命名优化】【表达式拆分】【抽取 / 封装】【格式与结构】【业务语义化】每一类带反面坏代码 优化后好代码结合你刚才那段 String 构造器的场景。一、分支与判断优化你重点问的调整顺序、拆分判断、减少嵌套1. 优先 fail-fast提前返回、提前抛异常把异常 / 非法分支放最前面规则异常、非法、边界 case 放前面正常主逻辑放后面尽早 return/throw消灭 else 嵌套 ❌ 坏嵌套深先正常逻辑再判断错误public String(char value[], int offset, int count) { if (offset 0 count 0) { if (count 0) { if(offset value.length){ this.value .value; }else{ throw new StringIndexOutOfBoundsException(offset); } }else if(offset value.length - count){ this.value Arrays.copyOfRange(value, offset, offsetcount); }else{ throw new StringIndexOutOfBoundsException(offsetcount); } }else{ if(offset 0) throw new StringIndexOutOfBoundsException(offset); if(count 0) throw new StringIndexOutOfBoundsException(count); } }✅ 好fail-fast非法前置扁平化public String(char value[], int offset, int count) { if (offset 0) { throw new StringIndexOutOfBoundsException(offset不能小于0 offset); } if (count 0) { throw new StringIndexOutOfBoundsException(count不能小于0 count); } if (count 0) { if (offset value.length) { throw new StringIndexOutOfBoundsException(offset); } this.value .value; return; } if (offset value.length - count) { throw new StringIndexOutOfBoundsException(offset count); } this.value Arrays.copyOfRange(value, offset, offset count); }2. 拆分复合判断不要一长串 || 挤在一行❌ 坏一堆条件揉在一起读的时候要心算if(offset 0 count 0 offset count value.length){ throw new StringIndexOutOfBoundsException(); }✅ 好拆成独立判断一个 if 只校验一个规则复杂条件抽变量boolean isOffsetValid offset 0; boolean isCountValid count 0; boolean isRangeOverFlow offset value.length - count; if (!isOffsetValid) { throw new StringIndexOutOfBoundsException(offset非法); } if (!isCountValid) { throw new StringIndexOutOfBoundsException(count非法); } if (isRangeOverFlow) { throw new StringIndexOutOfBoundsException(区间越界); }3.消除 if-else 金字塔卫语句、反转条件口诀正向长逻辑反转条件提前 return❌ 金字塔嵌套if(student ! null){ if(student.getScore() 60){ if(student.getAge() 12){ return 合格; } } } return 不合格;✅ 卫语句写法if (student null) return 不合格; if (student.getScore() 60) return 不合格; if (student.getAge() 12) return 不合格; return 合格;4. 分支顺序高频 case 放前面业务场景大部分请求都是正常还是异常多校验类代码工具、构造器异常 / 非法前置fail-fast业务判断命中最多的分支放最前面减少无效判断示例大部分订单都是已支付 ❌ 坏低频分支放前面if(OrderStatus.CANCEL.equals(status)){ ... } else if(OrderStatus.REFUND.equals(status)){ ... } else if(OrderStatus.PAID.equals(status)){ ... } // 最多放最后✅ 好if(OrderStatus.PAID.equals(status)){ ... } // 高频优先 else if(OrderStatus.CANCEL.equals(status)){ ... } else if(OrderStatus.REFUND.equals(status)){ ... }5. 少用 else优先 return能用 switch 枚举就不要超长 if elseJava14 switch 表达式可读性远强于 if-else 链条二、注释优化重点注释写【为什么】不写【做什么】三类注释文档注释、难点注释、反直觉注释禁止复述代码 ❌ 坏注释复述代码垃圾注释// 如果offset小于0抛出异常 if(offset 0) throw new StringIndexOutOfBoundsException(offset);✅ 好注释解释约束、风险、设计原因解决 “为什么这么写”// 防int溢出不要写成 offset count value.length // 当offset/count接近Integer.MAX_VALUE时相加溢出变负数校验失效 if (offset value.length - count) { throw new StringIndexOutOfBoundsException(offset count); }✅ 文档注释对外暴露方法说明入参、异常、边界行为/** * 根据字符数组的指定区间构造字符串 * param value 源字符数组 * param offset 起始下标从0开始 * param count 需要截取的字符数量 * throws StringIndexOutOfBoundsException offset负数 / count负数 / 区间超出数组范围 */补充注释规范简单自解释代码不加注释多余注释反而干扰阅读业务特殊规则、历史坑、兼容逻辑、性能取舍必须写注释复杂算法、数学判断、溢出风险、并发约束必须写注释三、命名优化性价比最高好名字可以少写一半注释变量 / 方法 / 类名表达意图而不是表达类型 ❌ 坏命名int a; // a是offset int b; // b是count boolean flag; ListStudent list1;✅ 好命名int startIndex; int takeCharNum; boolean isRangeValid; ListStudent passStudentList;命名细则布尔is/has/can/should 开头isOverFlow、hasPermission方法动词开头validateRange、copySubCharArray避免缩写除非团队共识idx 这种通用缩写可以不要加冗余后缀studentObj、infoDTO尽量少四、表达式拆分 抽取中间变量把复杂计算、判断抽成语义变量适合长表达式、三元嵌套、连续计算 ❌ 坏一行塞下复杂逻辑阅读需要大脑缓存多个值if ((order.getPayTime() ! null order.getPayTime().isAfter(LocalDateTime.now().minusDays(7))) order.getAmount().compareTo(new BigDecimal(100)) 0) { sendNotice(); }✅ 好抽变量每个变量自带语义LocalDateTime sevenDaysAgo LocalDateTime.now().minusDays(7); boolean isPaidRecently order.getPayTime() ! null order.getPayTime().isAfter(sevenDaysAgo); boolean isAmountOver100 order.getAmount().compareTo(new BigDecimal(100)) 0; if (isPaidRecently isAmountOver100) { sendNotice(); }小提醒不要过度抽取简单判断不用拆五、抽取函数 / 方法单一职责一个方法只做一件事把一组强相关的判断、校验逻辑抽成独立方法方法名代替注释 拿我们 String 构造器的校验举例 ❌ 全部堆在构造器里一大坨 ✅ 抽取校验方法public String(char value[], int offset, int count) { validateCharRange(value, offset, count); if (count 0) { this.value .value; return; } this.value Arrays.copyOfRange(value, offset, offset count); } /** * 校验字符数组截取区间合法性 */ private static void validateCharRange(char[] value, int offset, int count) { if (offset 0) { throw new StringIndexOutOfBoundsException(offset非法: offset); } if (count 0) { throw new StringIndexOutOfBoundsException(count非法: count); } if (count 0 offset value.length) { throw new StringIndexOutOfBoundsException(offset); } if (offset value.length - count) { throw new StringIndexOutOfBoundsException(offset count); } }好处主流程干净一眼看到【校验 → 拷贝】校验逻辑可以复用单元测试好写。延伸超大方法按阶段拆参数校验、数据组装、调用下游、结果封装分开工具类通用校验统一放到XXXValidator六、数据结构 常量 枚举消除魔法值、魔法字符串可读性重灾区硬编码数字字符串 ❌ 坏魔法值没人知道 1、2、3 代表什么if(status 1){ return 成功; }else if(status 2){ return 退款; }✅ 方案 1常量private static final int STATUS_SUCCESS 1; private static final int STATUS_REFUND 2;✅ 方案 2优先枚举自带语义public enum OrderStatus { SUCCESS, REFUND, CANCEL }七、格式、留白、代码排版低成本见效快一组逻辑之间空一行分割校验区空一行业务逻辑区空一行不要全部挤成密不透风// 校验区 if (offset 0) { throw new StringIndexOutOfBoundsException(offset不能小于0 offset); } if (count 0) { throw new StringIndexOutOfBoundsException(count不能小于0 count); } // 空一行分割区分阶段 if (count 0) { if (offset value.length) { throw new StringIndexOutOfBoundsException(offset); } this.value .value; return; }统一缩进不要混用 tab 空格不要单行放多个语句禁止if(a) return; b;挤一行除了极简单卫语句运算符前后加空格八、避免晦涩写法优先直白写法牺牲一点点花哨换可读性很多高级写法写起来短但别人读着费劲 ❌ 晦涩连续三元、复杂 stream 嵌套、位运算不加注释String res score 60 ? (age12 ? pass:reject) : reject;✅ 直白卫语句更容易看懂if (score 60) return reject; if (age 12) return reject; return pass;取舍团队内达成共识的简洁写法简单 stream可以保留业务主链路禁止炫技九、封装领域模型把判断下沉到对象内部面向对象层面把和一个实体绑定的判断逻辑放到实体自身方法里不要散落在各个 if ❌ 到处写判断if(student.getScore() 60 student.getAge()12){}✅ 下沉到实体// Student类内 public boolean isQualified(){ return this.score 60 this.age 12; } // 使用处 if(student.isQualified()){} 总表汇总方便你记忆、复盘表格分类手段一句话说明分支判断fail-fast / 卫语句、反转条件非法分支前置提前 return/throw消灭 else 嵌套分支判断调整分支顺序校验类异常优先业务类高频 case 优先分支判断拆分复合条件长 拆成多个独立 if抽布尔变量注释为什么而不是做什么只注释风险、约束、历史坑、反直觉逻辑拒绝复述代码命名语义化命名名字表达意图布尔 is/has方法动词开头表达式抽取中间变量复杂判断、计算抽成带名字的变量职责拆分抽取小方法一个方法只做一件事把校验 / 组装单独抽常量枚举消灭魔法数字字符串硬编码值全部收拢到常量或枚举排版格式留白、分段逻辑块之间空行缩进规范写法风格拒绝炫技晦涩代码优先直白写法业务代码可读性 简短OO 层面行为下沉到领域对象和实体相关的判断封装进实体方法✨ 记忆口诀方便背命名先行注释慎加非法前置尽早返回长式拆变量逻辑抽小方法魔法值收枚举少写嵌套金字塔排版留白分段不写花哨玄学。 
长河君 · 2026/10/31 2:05:05 · 阅读 1.2k java代码可读性优化全方案
核心原则先让错误提前暴露、减少人脑上下文负担、降低阅读时的推理成本分为 6 大类【分支与判断优化】【注释 命名优化】【表达式拆分】【抽取 / 封装】【格式与结构】【业务语义化】每一类带反面坏代码 优化后好代码结合你刚才那段 String 构造器的场景。一、分支与判断优化你重点问的调整顺序、拆分判断、减少嵌套1. 优先 fail-fast提前返回、提前抛异常把异常 / 非法分支放最前面规则异常、非法、边界 case 放前面正常主逻辑放后面尽早 return/throw消灭 else 嵌套 ❌ 坏嵌套深先正常逻辑再判断错误public String(char value[], int offset, int count) { if (offset 0 count 0) { if (count 0) { if(offset value.length){ this.value .value; }else{ throw new StringIndexOutOfBoundsException(offset); } }else if(offset value.length - count){ this.value Arrays.copyOfRange(value, offset, offsetcount); }else{ throw new StringIndexOutOfBoundsException(offsetcount); } }else{ if(offset 0) throw new StringIndexOutOfBoundsException(offset); if(count 0) throw new StringIndexOutOfBoundsException(count); } }✅ 好fail-fast非法前置扁平化public String(char value[], int offset, int count) { if (offset 0) { throw new StringIndexOutOfBoundsException(offset不能小于0 offset); } if (count 0) { throw new StringIndexOutOfBoundsException(count不能小于0 count); } if (count 0) { if (offset value.length) { throw new StringIndexOutOfBoundsException(offset); } this.value .value; return; } if (offset value.length - count) { throw new StringIndexOutOfBoundsException(offset count); } this.value Arrays.copyOfRange(value, offset, offset count); }2. 拆分复合判断不要一长串 || 挤在一行❌ 坏一堆条件揉在一起读的时候要心算if(offset 0 count 0 offset count value.length){ throw new StringIndexOutOfBoundsException(); }✅ 好拆成独立判断一个 if 只校验一个规则复杂条件抽变量boolean isOffsetValid offset 0; boolean isCountValid count 0; boolean isRangeOverFlow offset value.length - count; if (!isOffsetValid) { throw new StringIndexOutOfBoundsException(offset非法); } if (!isCountValid) { throw new StringIndexOutOfBoundsException(count非法); } if (isRangeOverFlow) { throw new StringIndexOutOfBoundsException(区间越界); }3.消除 if-else 金字塔卫语句、反转条件口诀正向长逻辑反转条件提前 return❌ 金字塔嵌套if(student ! null){ if(student.getScore() 60){ if(student.getAge() 12){ return 合格; } } } return 不合格;✅ 卫语句写法if (student null) return 不合格; if (student.getScore() 60) return 不合格; if (student.getAge() 12) return 不合格; return 合格;4. 分支顺序高频 case 放前面业务场景大部分请求都是正常还是异常多校验类代码工具、构造器异常 / 非法前置fail-fast业务判断命中最多的分支放最前面减少无效判断示例大部分订单都是已支付 ❌ 坏低频分支放前面if(OrderStatus.CANCEL.equals(status)){ ... } else if(OrderStatus.REFUND.equals(status)){ ... } else if(OrderStatus.PAID.equals(status)){ ... } // 最多放最后✅ 好if(OrderStatus.PAID.equals(status)){ ... } // 高频优先 else if(OrderStatus.CANCEL.equals(status)){ ... } else if(OrderStatus.REFUND.equals(status)){ ... }5. 少用 else优先 return能用 switch 枚举就不要超长 if elseJava14 switch 表达式可读性远强于 if-else 链条二、注释优化重点注释写【为什么】不写【做什么】三类注释文档注释、难点注释、反直觉注释禁止复述代码 ❌ 坏注释复述代码垃圾注释// 如果offset小于0抛出异常 if(offset 0) throw new StringIndexOutOfBoundsException(offset);✅ 好注释解释约束、风险、设计原因解决 “为什么这么写”// 防int溢出不要写成 offset count value.length // 当offset/count接近Integer.MAX_VALUE时相加溢出变负数校验失效 if (offset value.length - count) { throw new StringIndexOutOfBoundsException(offset count); }✅ 文档注释对外暴露方法说明入参、异常、边界行为/** * 根据字符数组的指定区间构造字符串 * param value 源字符数组 * param offset 起始下标从0开始 * param count 需要截取的字符数量 * throws StringIndexOutOfBoundsException offset负数 / count负数 / 区间超出数组范围 */补充注释规范简单自解释代码不加注释多余注释反而干扰阅读业务特殊规则、历史坑、兼容逻辑、性能取舍必须写注释复杂算法、数学判断、溢出风险、并发约束必须写注释三、命名优化性价比最高好名字可以少写一半注释变量 / 方法 / 类名表达意图而不是表达类型 ❌ 坏命名int a; // a是offset int b; // b是count boolean flag; ListStudent list1;✅ 好命名int startIndex; int takeCharNum; boolean isRangeValid; ListStudent passStudentList;命名细则布尔is/has/can/should 开头isOverFlow、hasPermission方法动词开头validateRange、copySubCharArray避免缩写除非团队共识idx 这种通用缩写可以不要加冗余后缀studentObj、infoDTO尽量少四、表达式拆分 抽取中间变量把复杂计算、判断抽成语义变量适合长表达式、三元嵌套、连续计算 ❌ 坏一行塞下复杂逻辑阅读需要大脑缓存多个值if ((order.getPayTime() ! null order.getPayTime().isAfter(LocalDateTime.now().minusDays(7))) order.getAmount().compareTo(new BigDecimal(100)) 0) { sendNotice(); }✅ 好抽变量每个变量自带语义LocalDateTime sevenDaysAgo LocalDateTime.now().minusDays(7); boolean isPaidRecently order.getPayTime() ! null order.getPayTime().isAfter(sevenDaysAgo); boolean isAmountOver100 order.getAmount().compareTo(new BigDecimal(100)) 0; if (isPaidRecently isAmountOver100) { sendNotice(); }小提醒不要过度抽取简单判断不用拆五、抽取函数 / 方法单一职责一个方法只做一件事把一组强相关的判断、校验逻辑抽成独立方法方法名代替注释 拿我们 String 构造器的校验举例 ❌ 全部堆在构造器里一大坨 ✅ 抽取校验方法public String(char value[], int offset, int count) { validateCharRange(value, offset, count); if (count 0) { this.value .value; return; } this.value Arrays.copyOfRange(value, offset, offset count); } /** * 校验字符数组截取区间合法性 */ private static void validateCharRange(char[] value, int offset, int count) { if (offset 0) { throw new StringIndexOutOfBoundsException(offset非法: offset); } if (count 0) { throw new StringIndexOutOfBoundsException(count非法: count); } if (count 0 offset value.length) { throw new StringIndexOutOfBoundsException(offset); } if (offset value.length - count) { throw new StringIndexOutOfBoundsException(offset count); } }好处主流程干净一眼看到【校验 → 拷贝】校验逻辑可以复用单元测试好写。延伸超大方法按阶段拆参数校验、数据组装、调用下游、结果封装分开工具类通用校验统一放到XXXValidator六、数据结构 常量 枚举消除魔法值、魔法字符串可读性重灾区硬编码数字字符串 ❌ 坏魔法值没人知道 1、2、3 代表什么if(status 1){ return 成功; }else if(status 2){ return 退款; }✅ 方案 1常量private static final int STATUS_SUCCESS 1; private static final int STATUS_REFUND 2;✅ 方案 2优先枚举自带语义public enum OrderStatus { SUCCESS, REFUND, CANCEL }七、格式、留白、代码排版低成本见效快一组逻辑之间空一行分割校验区空一行业务逻辑区空一行不要全部挤成密不透风// 校验区 if (offset 0) { throw new StringIndexOutOfBoundsException(offset不能小于0 offset); } if (count 0) { throw new StringIndexOutOfBoundsException(count不能小于0 count); } // 空一行分割区分阶段 if (count 0) { if (offset value.length) { throw new StringIndexOutOfBoundsException(offset); } this.value .value; return; }统一缩进不要混用 tab 空格不要单行放多个语句禁止if(a) return; b;挤一行除了极简单卫语句运算符前后加空格八、避免晦涩写法优先直白写法牺牲一点点花哨换可读性很多高级写法写起来短但别人读着费劲 ❌ 晦涩连续三元、复杂 stream 嵌套、位运算不加注释String res score 60 ? (age12 ? pass:reject) : reject;✅ 直白卫语句更容易看懂if (score 60) return reject; if (age 12) return reject; return pass;取舍团队内达成共识的简洁写法简单 stream可以保留业务主链路禁止炫技九、封装领域模型把判断下沉到对象内部面向对象层面把和一个实体绑定的判断逻辑放到实体自身方法里不要散落在各个 if ❌ 到处写判断if(student.getScore() 60 student.getAge()12){}✅ 下沉到实体// Student类内 public boolean isQualified(){ return this.score 60 this.age 12; } // 使用处 if(student.isQualified()){} 总表汇总方便你记忆、复盘表格分类手段一句话说明分支判断fail-fast / 卫语句、反转条件非法分支前置提前 return/throw消灭 else 嵌套分支判断调整分支顺序校验类异常优先业务类高频 case 优先分支判断拆分复合条件长 拆成多个独立 if抽布尔变量注释为什么而不是做什么只注释风险、约束、历史坑、反直觉逻辑拒绝复述代码命名语义化命名名字表达意图布尔 is/has方法动词开头表达式抽取中间变量复杂判断、计算抽成带名字的变量职责拆分抽取小方法一个方法只做一件事把校验 / 组装单独抽常量枚举消灭魔法数字字符串硬编码值全部收拢到常量或枚举排版格式留白、分段逻辑块之间空行缩进规范写法风格拒绝炫技晦涩代码优先直白写法业务代码可读性 简短OO 层面行为下沉到领域对象和实体相关的判断封装进实体方法✨ 记忆口诀方便背命名先行注释慎加非法前置尽早返回长式拆变量逻辑抽小方法魔法值收枚举少写嵌套金字塔排版留白分段不写花哨玄学。