global-coding-governance/java-coding-style/references/01-命名格式与注释.md

命名、格式与注释

命名

• 必须：类、接口和枚举使用 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/匿名类/嵌套调用、需要突出语义阶段或格式化工具强制时换行。

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

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

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

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

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

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

避免拆开单个简短条件：

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 必须替换为实际首次创建日期，不得原样保留：

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