4.3 KiB
4.3 KiB
命名、格式与注释
命名
- 必须：类、接口和枚举使用
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。
导入
- 必须：禁止通配符导入。
- 推荐：按静态导入、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
*/