# 代码注释

编写或评审前端实现时应用本文件。

## 原则

- 意图优先靠**命名、类型与结构**表达；注释用于说明**为什么**、**约束与背景**，而不是复述代码在做什么。
- 避免「整文件零注释」：在**非显而易见**处用**简短**注释降低误改成本，与「不写废话注释」不矛盾。

## 应当注释的情况

- **业务或产品规则**：权限、展示条件、校验逻辑背后的依据（与需求或领域约定相关时）。
- **非直观的实现或取舍**：为何选用当前写法（性能、兼容、与后端/第三方约定等）。
- **外部契约**：与接口、设计稿、枚举或单位相关的字段含义、映射关系。
- **临时方案与技术债**：`TODO` / `FIXME` 应写明预期收尾或关联工单（若有）。
- **易踩坑点**：第三方库版本差异、必须满足的调用顺序、已知限制。

## 应避免的情况

- 逐行翻译已能从代码直接看出的行为。
- 注释与实现长期不一致；修改逻辑时同步更新或删除误导性注释。
- 用大段注释代替应抽取的函数或应补全的类型。

## 形式建议

- 语言与仓库现有注释保持一致（中文或英文）。
- 复杂模块或组件可在文件顶部用 **1～3 行** 说明职责与关键约束；跨包或对外导出的 API 宜用 **JSDoc** 说明参数、返回值与副作用。
- 复杂条件分支或 `useEffect`：若依赖或触发条件不直观，用一行说明**触发条件**或**不变量**。
- 临时规避、兼容旧系统或性能取舍必须说明原因和退出条件。

## 文档同步

当修改公开命令、skill、agent、模板、报告命名或安装路径时，同步更新 README、runtime docs、项目结构文档和多语言说明。注释解释局部代码，公开文档解释团队如何使用能力，两者不要互相替代。