|
|
@@ -1,29 +1,29 @@
|
|
|
---
|
|
|
-description: 业务代码必须用中文说明新增/改动部分的用途与要解决的问题
|
|
|
+description: 在业务源码中写简体中文注释（不是另写文档）
|
|
|
alwaysApply: true
|
|
|
---
|
|
|
|
|
|
-# 代码中文说明（必遵）
|
|
|
+# 代码中文注释（必遵）
|
|
|
|
|
|
-在本仓库（`D:/front-end`）及关联后端 `D:/phpstudy_pro/WWW/huahuibao` 中，对**新增或实质改动**的代码补充清晰**简体中文**说明。完整细则见 `D:/understand-project/knowledge/code-comments-cn.md`。
|
|
|
+在本仓库写代码时，把**简体中文注释直接写在源码里**（`//`、`/* */`、`/** */`、`<!-- -->` 等）。细则：`D:/understand-project/knowledge/code-comments-cn.md`。
|
|
|
|
|
|
-## 必须说明的对象
|
|
|
+## 必须做
|
|
|
|
|
|
-- **新建文件**：文件顶部块注释 — 用途、谁调用、解决什么问题、与哪条 API/页面/表相关（若适用）。
|
|
|
-- **新增/改动的函数、方法、类、组件、导出**：定义上方 — 职责、入参/返回业务含义、副作用、关键边界。
|
|
|
-- **非显而易见的逻辑块**：分支、权限、库存/金额、状态流转 — 写清**业务规则**，不只复述代码。
|
|
|
+- **新建/改动的文件**：文件顶部块注释 — 用途、谁用、解决什么问题。
|
|
|
+- **新建/改动的函数、方法、类、组件**：定义上方注释 — 职责、入参/返回业务含义、副作用、关键边界。
|
|
|
+- **复杂分支**：关键逻辑**行前**注释 — 写清业务规则。
|
|
|
|
|
|
-## 写法要求
|
|
|
+每条注释回答：**干什么** + **为什么**。
|
|
|
|
|
|
-- 回答：**干什么** + **为什么（解决什么问题）**。
|
|
|
-- 与接口/表/产品相关时点名（如 `ghsApp`、`app-ghs`），便于用 `D:/understand-project` 的 `npm run context` 串联。
|
|
|
-- 不写空话（「优化」「处理」）；不堆砌类型已表达的信息。
|
|
|
-- 仅格式/错别字/无行为变更时可不加新注释。
|
|
|
+## 禁止
|
|
|
|
|
|
-## 全栈一致
|
|
|
+- 用 Markdown/README/知识库文章**代替**源码注释。
|
|
|
+- 只口头或在外部项目里说明，却不给本仓库 `.vue`/`.js` 加注释。
|
|
|
|
|
|
-改 API 时，本仓库 `src/api` / `src/service` 与后端 Controller/Class 的中文说明应对同一业务行为，表述一致。
|
|
|
+## 全栈
|
|
|
+
|
|
|
+改 API 时，`src/api` / `src/service` 与后端 Controller/Class **源码注释**表述一致。
|
|
|
|
|
|
## 例外
|
|
|
|
|
|
-用户当次明确要求不要注释或仅英文时，服从当次指令并在回复中简要说明。
|
|
|
+用户当次明确要求不要注释或仅英文时，服从当次指令。
|
