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

2026-08-20 09:21:07 +08:00
parent 54c21876e4
commit d8da9c7b1a
7 changed files with 10 additions and 10 deletions
@@ -37,7 +37,7 @@ No automated tests (manual smoke only)
 Environment: Node 18.20.7, npm mirror `https://registry.npmmirror.com`. Before local integration, adjust `vite.config.ts` (`build.outDir` → target service's `resources/html/vue/<app>/`; `server.proxy` → target backend) and `public/data/data.js` (`currentSubsystem`). After a framework upgrade, run `npm install`; never overwrite `public`, `vite.config.ts`, or `src/subsystem`.

 ## Architecture & Coding Style
-Use TypeScript, 2-space indentation. Kebab-case files, PascalCase component names (must equal the route `name`), `getXxx`/`saveXxx` API function names. Do not add modules that are not registered in `ARCHITECTURE.md`. Preserve the dependency DAG; no reverse dependencies and no cross-module private access. Avoid empty names such as `Manager`, `Helper`, `Util`, `Common`, `Misc`, or `Tools`.
+Use TypeScript, 2-space indentation. Kebab-case files, PascalCase component names (must equal the route `name`), `getXxx`/`saveXxx` API function names. **Every method/function must carry a one-line responsibility comment** (manual-review friendly). Do not add modules that are not registered in `ARCHITECTURE.md`. Preserve the dependency DAG; no reverse dependencies and no cross-module private access. Avoid empty names such as `Manager`, `Helper`, `Util`, `Common`, `Misc`, or `Tools`.

 UI/presentation code should consume state and send intents only — business logic goes into hooks/services; keep data-model types thin. Data access must go through the `request` wrapper (`src/framework/utils/request.ts`) — never raw `axios`/`fetch`; the wrapper handles service-alias mapping, token refresh, commonParam header, and response unwrapping (see shared spec §6).

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

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

@@ -49,7 +49,7 @@

 ### 2.5 注释

- 默认不写注释；只在 WHY 不明显时写一行；不写解释 WHAT 的注释。
+- 每个方法/函数必须写一行职责注释（便于人工复核）；只在 WHY 不明显处补充 WHY 注释；不写会随时间失效的注释。

 ## 3. 提交规范