# 命名、格式与注释

## 命名

- **必须**：类、接口和枚举使用 `UpperCamelCase`；方法、参数、字段和局部变量使用 `lowerCamelCase`；常量使用语义完整的 `UPPER_SNAKE_CASE`。
- **必须**：包名全小写，以稳定的组织与业务域命名；遵循项目现有单复数约定。
- **必须**：命名不得以 `_` 或 `$` 开头、结尾，不得使用中文、纯拼音或中英拼音混写。国际通用专名除外。
- **必须**：抽象基类使用 `Abstract` 或项目约定前缀；异常以 `Exception` 结尾；测试类遵循项目测试框架的现有命名。
- **必须**：避免无意义缩写、单字母业务变量和误导性名称。循环索引等极小作用域变量可以使用惯用短名。
- **必须**：Bean/序列化对象的布尔属性命名必须验证框架映射；默认不以 `is` 命名字段，访问器可按 JavaBeans 约定使用 `isXxx()`。
- **推荐**：DO、DTO、BO、VO、PO 等后缀只在项目已经定义其语义时使用，不自行发明相邻概念。
- **推荐**：实现设计模式时让类名表达职责，如 `OrderFactory`；不要仅为套用模式而改名。

## 常量与字面量

- **必须**：禁止散落的业务魔法值；提取为有领域含义的常量、枚举或值对象。
- **必须**：`long` 字面量使用大写 `L`。
- **必须**：不得用一个“万能常量类”承载所有模块常量；按模块和职责控制可见性。
- **推荐**：仅在真正固定且跨实例共享时声明 `static final`；不要把可变集合伪装成常量。
- **推荐**：状态和类型码优先使用有行为约束的枚举或值对象，同时保持对外协议兼容。

## 格式

- **必须**：服从项目 formatter、Checkstyle 或编辑器配置；不得因本文件偏好覆盖自动化格式规则。
- **必须**：控制语句始终使用大括号；关键字与左括号间保留空格；运算符两侧保留空格。
- **必须**：默认使用 4 空格缩进且不使用 Tab；项目 formatter 另有规定时从项目。
- **推荐**：单行不超过 120 字符；该限制是可读性上限，不是主动换行目标。import 和自动生成代码按工具配置处理。
- **推荐**：新增方法原则上不超过 80 行，新增类原则上不超过 500 行。生成代码、声明型配置或框架限制可例外，但应说明原因。
- **推荐**：方法保持聚焦，避免超过三层嵌套；优先使用卫语句、提取方法或清晰的布尔变量。
- **必须**：避免魔法值、重复代码、过深嵌套和无业务价值的抽象。
- **必须**：不要提交仅由全局换行、import 重排或格式化导致的无关 diff。

### 换行策略

- **必须**：采用紧凑优先原则。完整语句、方法签名或方法调用未超过项目行宽且保持清晰时，保留在同一行。
- **必须**：不要为了形式对称、固定“一行一个参数”或提前规避行宽而主动拆行。
- **必须**：方法声明、方法调用和构造器调用需要换行时，在不超过项目行宽的前提下保留尽可能多的完整参数；仅在参数本身复杂或项目格式化工具要求时采用“一行一个参数”。
- **必须**：布尔表达式需要换行时，将每个完整条件作为一个视觉单元，并按 `&&` 或 `||` 对齐；不要拆开简短的 `Objects.equals`、判空或比较表达式的参数。
- **推荐**：短方法链保留在同一行；长方法链需要换行时，每行保留一个语义完整的调用阶段。
- **推荐**：仅在超过项目行宽、包含复杂 Lambda/匿名类/嵌套调用、需要突出语义阶段或格式化工具强制时换行。

方法签名超过行宽时，优先紧凑续行：

```java
private boolean matchesRule(PmsProductDO product, ProductValidityRuleTypeEnum ruleType,
                            LocalDateTime thresholdEndExclusive) {
```

避免对每个参数机械换行：

```java
private boolean matchesRule(
        PmsProductDO product,
        ProductValidityRuleTypeEnum ruleType,
        LocalDateTime thresholdEndExclusive) {
```

布尔条件换行时，每个条件保持完整：

```java
return Objects.equals(product.getMerchantNature(), ProductAttributeConstant.MERCHANT_NATURE_MERCHANT)
        && Objects.equals(product.getVerifyStatus(), ProductVerifyStatusEnum.VERIFIED.getCode())
        && Objects.equals(product.getDeleteStatus(), DelStatusEnum.NOT_DELETED.getCode());
```

避免拆开单个简短条件：

```java
return Objects.equals(
        product.getMerchantNature(),
        ProductAttributeConstant.MERCHANT_NATURE_MERCHANT);
```

## 导入

- **必须**：禁止通配符导入。
- **推荐**：按静态导入、Java/Jakarta 标准库、第三方库、项目内部包分组，组间空一行。
- **推荐**：同组内按字典序排列；若项目格式化器定义了不同顺序，以格式化器为准。
- **必须**：删除未使用导入，不通过全限定类名规避正常导入。

## 注释与 Javadoc

- **必须**：公共 API、接口抽象方法和不显然的契约说明使用 Javadoc，包含参数约束、返回语义和可观察异常。
- **必须**：修改逻辑时同步更新相关注释；陈旧注释视为缺陷。
- **必须**：注释说明意图、业务原因、约束或权衡，不复述语句表面含义。
- **必须**：枚举字段或代码值必须能看出业务含义，可通过 Javadoc、构造参数或明确命名表达。
- **推荐**：TODO/FIXME 包含可追踪的任务标识和原因；若无跟踪机制则完成或删除。
- **必须**：不要保留大段注释掉的代码，版本历史可承担恢复职责。
- **必须**：所有新增类必须有 Javadoc，首句说明职责而非复述类名。
- **必须**：类 Javadoc 使用作者 `xiang`，通过 `@since` 记录实际首次创建日期，日期格式固定为 `yyyy-MM-dd`；后续修改不得覆盖首次创建日期。
- **推荐**：对复杂业务逻辑解释“为什么”和特殊规则，不逐行翻译代码；业务分支意图不明显时补充说明。
- **必须**：禁止保留 `yourname`、`TODO author` 等占位内容。

Javadoc 采用以下格式；`yyyy-MM-dd` 必须替换为实际首次创建日期，不得原样保留：

```java
/**
 * 类的职责说明
 *
 * @author xiang
 * @since yyyy-MM-dd
 */
```