# Code Comment

> 编写或修改代码注释时遵循的规范（含 javadoc、行内注释、字段注释、测试注释）。核心是「注释权责对齐当前作用域」——不向上溯源调用链、不向下探索消费方、阶段性现状带时间戳、不写行号、不脑补业务。写/改任何注释前使用本 skill。

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

---


# code-comment

——注释经常成为代码质量中被忽视的部分。烂注释比没有注释更危险，因为它会主动误导。

## 一、核心原则：注释权责对齐作用域

**注释的内容必须严格对齐当前方法/类/字段的作用域。** 非必要不在注释中超出本作用域，避免未来项目变更时注释腐化，变成误导他人的"屎山"。

具体禁止两类越界：

- **向上溯源**：写明谁调用了我、是不是唯一入口、由哪个上游保证了入参非空等。
- **向下探索**：写明我的产物流向哪里、被哪些下游消费、对哪些消费方有/无影响等。

### 错误案例 1：方法 javadoc 向上溯源

```java
/**
 * 搜索推送新模型的唯一入口：本应用所有推往搜索的 item 数据请求都收敛于此方法。
 * 调用来源：定时全量（FullSyncSchedulerJob）、binlog 增量（ItemBinlogConsumer）、
 * 手工后门（JobController#itemSyncBackDoor）。
 *
 * @param itemIds 待推送的条目 id 列表，为空时直接返回
 */
public void handleItemSearchData(List<Long> itemIds) { ... }
```

"唯一入口""都收敛于""调用来源""手工后门"——全部超出本方法权责，向上探索调用链。一旦新增/删除调用方，这些注释立刻过时误导人。

**正确写法**（聚焦本方法做什么）：

```java
/**
 * 处理待推送的搜索条目数据：按 itemId 拉取明细、构建搜索文档并推送。
 *
 * @param itemIds 待推送的条目 id 列表，为空时直接返回
 */
public void handleItemSearchData(List<Long> itemIds) { ... }
```

### 错误案例 2：字段注释向下探索消费链路

```java
/**
 * 内容地区归属：domestic（国内）/ overseas（海外）
 * 影响评估：本字段仅做单向序列化输出，输出去向为 databus topic ItemSearch-T
 * （SearchPublishService）及 FTP 文件（FtpScheduler）；新增本字段对现有调用方
 * 无破坏性影响，老的消费方按需取用、忽略未知字段即可。
 */
private String areaOwner;
```

"输出去向""消费方""对调用方无破坏性影响"——向下探索了字段的消费链路。下游一旦调整，注释即腐化。

**正确写法**（只描述字段语义）：

```java
/**
 * 条目地区归属：domestic（国内）/ overseas（海外）。
 */
private String areaOwner;
```

### 错误案例 3：行内注释跨方法引用 / 溯源

```java
// itemBaseInfo 非空由上游 buildItemSearchList 过滤保证（null 项不会进入本方法）
// 内容地区归属：当前不读库，直接兜底国内 domestic，与主链路 reduceItemSearchByItem 保持一致
```

"由上游 xxx 过滤保证""与主链路 xxx 保持一致"——既向上溯源又横向引用其他方法。

**正确写法**：

```java
// 条目地区归属：[注: 截至 2026-06-18] 不读库，直接兜底国内 domestic
```

---

## 二、五条强制约束

1. **专注当前作用域**：仅基于当前方法/类/字段的代码逻辑、入参、出参生成注释。严禁使用"唯一入口""都收敛于""调用来源""手工后门""由上游 xx 保证""与主链路 xx 一致""下游消费方""对调用方无影响"等描述外部调用链或横向引用其他方法的词汇。

2. **架构现状必须带时间戳**：如果确有必要在注释中说明**会随项目演进而变化的现状**（如"暂不读库直接兜底""目前仅支持 X 品类""临时方案"等），**必须**加时间标记，格式固定为 **`[注: 截至 YYYY-MM-DD]`**（**日粒度，不要用月粒度**）。例如：

   ```java
   // 条目地区归属：[注: 截至 2026-06-18] 不读库，直接兜底国内 domestic
   ```

   > 判定要点：描述的是"会过期的阶段性状态"才加时间戳；描述"稳定的代码逻辑/字段语义/确定的数据来源"则不需要。例如"当前条目""当前日期"这类**代码逻辑指代**（指运行时正在处理的对象）不是时间概念，不用加。

3. **禁止硬编码行号**：注释（尤其测试注释）中严禁出现"第 327 行""见第 948 行"等具体行号。代码一改行号即错，是高频腐化源。需要指向某处时，用**方法名/字段名引用**（如 `SearchService#buildItemSearchBackdoor`、`ItemDoc#getAreaOwner`），不写行号。

4. **禁止过度脑补**：严禁根据方法名/字段名自行猜测并生成未在当前代码块中体现的业务逻辑。不确定业务含义时，宁可只描述代码行为，也不要臆造业务背景。

5. **测试注释同样适用**：以上约束对单元测试注释一视同仁。测试 javadoc 推荐结构化描述「场景 / 覆盖目标 / 预期」，但同样不写行号、不堆砌"主链路""后门"等措辞，覆盖目标用方法名引用。

---

## 三、鼓励主动补充注释

约束是为了"不写坏注释"，不是为了"少写注释"。在不违反上述约束的前提下，**鼓励主动为以下情形补注释**：

- **非显而易见的取舍**：为什么选 A 方案而非 B、为什么兜底某个默认值、为什么这里要判空。
- **边界条件与坑点**：空集合/空指针的处理、越界风险、并发假设、幂等性。
- **复杂逻辑的意图**：一段不直观的算法/正则/位运算在"做什么、为什么"。
- **有意的"反常"代码**：看起来像 bug 实则有意为之的写法，注明原因避免被"好心改错"。

补注释时牢记：**写"为什么"，而非复述"做了什么"**（做了什么看代码即可）。

---

## 四、提交前自检清单

写完 / 改完注释，逐条过：

- [ ] 没有向上溯源（调用方、唯一入口、上游保证）
- [ ] 没有向下探索（产物去向、下游消费方、对调用方的影响）
- [ ] 没有横向引用其他方法做对比（"与 xx 保持一致"）
- [ ] 描述阶段性现状的，已加 `[注: 截至 YYYY-MM-DD]`（日粒度）
- [ ] 没有硬编码行号，指向他处用方法名/字段名引用
- [ ] 没有脱离代码事实的业务脑补
- [ ] 复杂逻辑/关键取舍/边界坑点已主动补注释，且写的是"为什么"
- [ ] 测试注释同样满足以上各条