---
description: 在业务源码中写简体中文注释（不是另写文档）
alwaysApply: true
---

# 代码中文注释（必遵）

在本仓库写代码时，把**简体中文注释直接写在源码里**（`//`、`/* */`、`/** */`、`<!-- -->` 等）。细则：`D:/understand-project/knowledge/code-comments-cn.md`。

## 必须做

- **新建/改动的文件**：文件顶部块注释 — 用途、谁用、解决什么问题。
- **新建/改动的函数、方法、类、组件**：定义上方注释 — 职责、入参/返回业务含义、副作用、关键边界。
- **复杂分支**：关键逻辑**行前**注释 — 写清业务规则。

每条注释回答：**干什么** + **为什么**。

## 禁止

- 用 Markdown/README/知识库文章**代替**源码注释。
- 只口头或在外部项目里说明，却不给本仓库 `.vue`/`.js` 加注释。

## 全栈

改 API 时，`src/api` / `src/service` 与后端 Controller/Class **源码注释**表述一致。

## 例外

用户当次明确要求不要注释或仅英文时，服从当次指令。