docs: 注释约定改为每方法必写（便于人工复核）

2026-08-20 09:21:07 +08:00
parent 54c21876e4
commit d8da9c7b1a
7 changed files with 10 additions and 10 deletions
@@ -36,7 +36,7 @@ No automated tests (manual smoke only)
 Environment: Nacos must be reachable (bootstrap.yml: server-addr/namespace; extension-configs pull abacus-database/discovery/acas/redis/actuator/xxljob); build depends on the company Maven private repo (abacus framework jars); set `<artifactId>` to `abacus.springboot.<app>`.

 ## Architecture & Coding Style
-Use Java, 4-space indentation, max line width 120. Controllers: `@RestController` + `@RequestMapping` + springdoc `@Tag`/`@Operation`; `throws Exception`; `@RequestParam(required=false)`; blank-param guard throws `BusinessException`; **return business objects directly** (the wrapper builds the unified response). Services orchestrate in `esb/`; raw SQL lives in `impl/` and MUST use `?` placeholders (no string concatenation). Entities: `@Entity @Table @JsonIgnoreProperties(ignoreUnknown=true) @Schema`, `@Id String`, `@Version Integer`, `STATUS_*` constants, hand-written getters/setters. Business IDs come from `DaoIdGenerator` beans — never hand-craft UUIDs.
+Use Java, 4-space indentation, max line width 120. **Every method must carry a one-line responsibility comment** (Javadoc style preferred; manual-review friendly). Controllers: `@RestController` + `@RequestMapping` + springdoc `@Tag`/`@Operation`; `throws Exception`; `@RequestParam(required=false)`; blank-param guard throws `BusinessException`; **return business objects directly** (the wrapper builds the unified response). Services orchestrate in `esb/`; raw SQL lives in `impl/` and MUST use `?` placeholders (no string concatenation). Entities: `@Entity @Table @JsonIgnoreProperties(ignoreUnknown=true) @Schema`, `@Id String`, `@Version Integer`, `STATUS_*` constants, hand-written getters/setters. Business IDs come from `DaoIdGenerator` beans — never hand-craft UUIDs.

 Do not add modules that are not registered in `ARCHITECTURE.md`. Preserve the dependency DAG; no reverse dependencies, no cross-feature imports, and no direct access to another module's private implementation. Avoid empty names such as `Manager`, `Helper`, `Util`, or `Common` for new code (legacy `util/`/`vo/` files are reference-only — cite but do not add).

@@ -42,8 +42,8 @@
 - 派生文档发现与上游不一致 → 回去改上游，不能让派生文档自走

 ### B4. 注释与命名
- 默认不写注释；只在 WHY 不明显时写一行。
- 不写解释 WHAT 的注释（命名应自解释）。
+- 每个方法/函数必须写注释（一行职责说明，便于人工复核）。
+- 只在 WHY 不明显处补充 WHY 注释；不写会随时间失效的注释。
 - 不写"为某 issue/任务而加"这类会随时间失效的注释。
 - 严格遵守 `CONVENTIONS.md` 中的命名规范（不存在则先补）。

@@ -50,7 +50,7 @@

 ### 2.5 注释

- 默认不写注释；只在 WHY 不明显时写一行；不写解释 WHAT 的注释（命名应自解释）。
+- 每个方法必须写注释（一行职责说明，复杂方法补充入参/出参/边界，便于人工复核）；只在 WHY 不明显处补充 WHY 注释；不写会随时间失效的注释。

 ## 3. 提交规范