Java编码规范的核心是预防线上故障与提升协作效率，包括命名清晰、布尔变量语义明确、Javadoc完整定义契约、避免过度内联、强制default分支及边界校验等。
Java 编码规范不是为了“看起来整齐”，而是为了避免 NullPointerException 在上线后凌晨三点把你叫醒，同时让新同事三天内能看懂你三个月前写的 processDataWithFlag 方法到底在 flag 为 false 时干了什么。
命名不清晰直接导致逻辑误读
很多团队把 user、u、temp 当作合法变量名，结果在 if (u != null && u.isActive() && temp.getStatus() == 1) 里没人敢动 temp ——它到底是临时对象、缓存副本，还是上一步的错误 fallback？
-
userId比id明确指向业务实体，避免和orderId、sessionId混淆 - 布尔变量必须用
is/has/can开头（如isRetryEnabled），否则retry在if (retry)中语义模糊 - 禁止用数字下划线拼接（如
data_2023），JVM 字节码对这类符号无特殊处理，但 IDE 重构时可能漏掉引用
public 方法没写 Javadoc 就等于没写契约
IDE 可以提示方法签名，但不会告诉你 calculateFee(Order order, boolean includeTax) 在 order.getItems() 为空时返回 0 还是抛 IllegalArgumentException。没有 Javadoc 的 public 方法，在协作中实际等价于未定义行为。
- 每个
@param必须说明取值范围（例如：@param timeoutMs 范围 100–30000，0 表示无限等待） -
@throws不仅要写异常类型，还要写触发条件（例如：@throws IllegalStateException 当调用前未执行 init()） - 静态工具类方法（如
StringUtils.isEmpty()）的 Javadoc 必须覆盖null输入行为，这是高频空指针源头
过度内联条件表达式掩盖控制流风险
把五层嵌套的 if 压成一行三元运算，看似“简洁”，实则让 Optional.ofNullable(user).map(User::getProfile).filter(p -> p.isVerified()).map(Profile::getEmail).orElse(null) 这种链式调用在 NPE 发生时无法快速定位是 user、profile 还是 email 为 null。
立即学习“Java免费学习笔记（深入）”；
- 任何超过两个逻辑操作符（
&&/||）的条件判断，必须拆成独立变量并命名（如isEligibleForDiscount = user.isVip() && order.getTotal() > 1000 && !user.hasUsedDiscountToday();） -
switch必须有default分支，即使只是抛IllegalArgumentException——枚举新增值时编译器不会报错，但运行时会静默跳过 - 禁止在
return前做副作用操作（如return log.warn("fail") || false;），这种写法会让代码审查完全失效
public BigDecimal calculateFee(Order order, boolean includeTax) {
if (order == null) {
throw new IllegalArgumentException("order must not be null");
}
if (order.getItems().isEmpty()) {
return BigDecimal.ZERO; // 明确边界行为，而非依赖隐式返回
}
BigDecimal base = order.getItems().stream()
.map(Item::getPrice)
.reduce(BigDecimal.ZERO, BigDecimal::add);
return includeTax ? base.multiply(TAX_RATE) : base;
}
可维护性最常被忽略的一点：规范不是用来“检查”的，而是当某行代码让你犹豫“这里改会不会影响别的模块”时，规范已经提前把决策路径标好了。真正危险的不是违反规范，而是发现规范里没写清楚——那说明你正站在设计模糊区的边缘。
