# Yy Comment

> 为代码添加注释。当用户要求"加注释"、"添加文档注释"、"补充注释"、 "写 docstring"、"加 Javadoc"、"给模板加注释"、"给样式加注释"时触发。 不适用于：实现新功能、修改代码逻辑、删除代码，或为每行代码强制加注释。

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

---


# yy-comment

## 描述

为代码添加注释的通用技能，支持多种编程语言和标记语言。遵循跨语言通用规则，并按语言加载特定注释规范；语言特定规则与通用规则冲突时，以语言特定规则优先。

## 使用场景

当用户表达以下意图时触发：

- 为代码文件或指定函数/类/方法添加注释
- 补充文档注释（docstring、Javadoc、KDoc、PHPDoc 等）
- 为代码逻辑添加解释性注释
- 为 HTML/Vue 模板添加结构注释
- 为 CSS/SCSS/LESS 添加样式注释

不应触发：

- 用户要求实现新功能、修改代码逻辑或删除代码
- 文件已有完整注释且用户未明确要求补充
- 用户要求为每行代码都加注释（过度注释）

## 规则层级

通用规则定义在 `resources/common.md`，语言特定规则定义在 `resources/{语言}.md`。

**当特定语言的规则与通用规则冲突时，以特定语言的规则优先。**

## 支持的语言

- Python → `resources/python.md`
- Java → `resources/java.md`
- C/C++ → `resources/c-cpp.md`
- C# → `resources/csharp.md`
- Go → `resources/go.md`
- Rust → `resources/rust.md`
- Swift → `resources/swift.md`
- Kotlin → `resources/kotlin.md`
- Ruby → `resources/ruby.md`
- PHP → `resources/php.md`
- Shell/Bash → `resources/shell.md`
- SQL → `resources/sql.md`
- JavaScript/TypeScript → `resources/js-ts.md`
- HTML/CSS → `resources/html-css.md`

遇到未列出语言的文件时，使用通用规则和该语言的注释语法常识处理。

## 指令

### 步骤 1. 确定范围

**决策分支**：

- **用户指定文件**：读取目标文件
- **用户指定函数/类/方法**：定位目标
- **用户未指定**：通过 `git diff` 查找变更文件，过滤为支持类型的文件

对于超过 500 行的文件，先告知用户文件规模，确认后再执行。

### 步骤 2. 识别语言并加载规则

- 根据文件扩展名识别语言
- 加载 `resources/common.md` 中的通用规则
- 加载 `resources/{语言}.md` 中的语言特定规则（如存在）
- 当特定语言的规则与通用规则冲突时，以语言特定规则优先

### 步骤 3. 添加注释

按通用规则和语言特定规则执行：

- 为函数/类/方法/接口添加文档注释
- 为重要模块级常量和类型定义添加注释
- 在关键逻辑步骤前添加内部注释（解释"为什么"）
- 跳过自解释代码和显而易见的逻辑
- 已有注释内容正确则保留，仅在缺失处补充；内容过时则修正

### 步骤 4. 输出结果

修改目标文件后，报告：

- 添加了注释的函数/类/接口/模块列表
- 各类注释数量：文档注释 N 处、内部逻辑注释 N 处

## 安全边界

- 不修改代码逻辑、不删除已有代码
- 不删除已有的正确注释
- 不为自解释代码强制添加注释
- 不修改自动生成的代码文件（如构建产物、编译输出）

---

## 相关资源

- `resources/common.md` - 跨语言通用注释规则（判断标准、避免模式、标注约定）
- `resources/{语言}.md` - 各语言特有的注释语法和规范