# Comment

> 在当前仓库新增或修改代码文件时使用。注释补充属于代码改动交付的一部分，重点约束中文注释、函数备注、变量类型声明，以及按功能模块组织的 template、script、type 注释分隔。

- Skill: `ls1072502993/comment` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ls1072502993/comment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ls1072502993/comment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ls1072502993 (https://skillmd.com/u/ls1072502993)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ls1072502993/comment

---


# 注释规则

## 规则执行方式（强制）

- 本 skill 一旦命中，本文件中的全部规则、流程、检查和交付条件默认全部执行，不得自行挑选或只执行部分内容。
- 仅允许跳过规则正文明确限定且当前条件不成立的条款；不得因改动小、只读文件、只回答问题或只执行命令而跳过已命中的规则。
- 多个 skill 同时命中时，叠加执行全部相关规则；交付前逐条确认已落实，未完成时不得宣告任务完成。

## 适用场景

- 在当前仓库内新增或修改代码时使用。
- 只要发生代码改动，默认同步命中本 skill，不得跳过。
- 只要当前代码改动链路中存在需要补充注释的地方，就必须按功能模块补充对应注释。

## 必须遵守

- 新增或修改代码时，补充简略注释，说明代码用途或关键逻辑。
- 新增或修改函数、方法时，为每个函数或方法补充简略备注。
- 新增或修改变量定义时，补充清晰直接的类型声明。
- 注释补充属于代码改动的交付约束，不是只有用户显式要求时才执行的可选优化项。
- 只要当前改动涉及需要补充注释的代码区域，必须按功能模块补充注释，不得只补局部零散注释。
- 注释保持简短直接，不写逐行解释，不写与代码语义重复的内容。

## 注释格式

- `script` 中函数和方法的大类集中放在同一个代码块中。
- `script` 分块统一使用：

```text
/******************************** xxxxxx ********************************/
```

- `TypeScript` 类型文件中的类型定义按模块集中放在同一个代码块中。
- 类型模块分隔统一使用：

```text
/******************************** xxxxxx ********************************/
```

- 类型模块内的分类型说明统一使用：

```text
// xxxxxx
```

- 代码块中的函数、方法备注统一使用：

```text
// xxxxxx
```

- `template` 模板中每个模块之间统一使用：

```html
<!-------------------------- xxxxxx -------------------------->
```

- `template`、`script`、`type` 中新增或修改的注释，都要优先按功能模块组织后再补充。

## 执行顺序

1. 开始代码改动前，先判断当前改动涉及哪些功能模块。
2. 编写或调整代码时，同步补齐该模块需要的模板注释、分块注释、函数备注和必要的中文说明。
3. 结束代码改动前，逐项确认当前改动链路内的注释完整。

## 执行提醒

- 除注释规范外，其余执行习惯继续遵循 `frontend-global`。
- 注释风格与现有文件保持一致，不主动重构已有结构。
- 在结束当前代码改动前，确认 `template` 模块分隔注释、`script` 分块注释、函数备注和改动点中文说明全部齐全。