注释约定

CLAUDE.md 第 7 条。写代码前先读，照此保持。

只写代码读不出来的「为什么」

• 注释只写 非显然的取舍、踩坑点、与惯常做法的有意差异。
• 不写代码已自解释的「是什么」。

禁止

• ❌ 堆砌「对照 Java XxxAspect.doBefore / 对照 Xxx.yyy」这类 方法级映射说明。
• ❌ 在函数上方写 逐行重复实现步骤的流水账。
• ❌ // XxxApiApp 包级实例。 这种纯自解释噪声。
• ❌ 错误变量上重述消息的一行（// ErrUserNotFound 用户不存在。 —— 错误文本已自述）。

保留

• ✅ 中间件顺序的动机：// 鉴权排在防重之前，未授权请求不该白占一个防重锁。
• ✅ 踩坑点：// 路径用 "" 而非 "/"：后者会注册成 /user/。
• ✅ 有意差异：// 存在性判定不靠受影响行数：值与库中完全相同时 MySQL 报 0 行，会把幂等重复保存误报成"不存在"。
• ✅ wire-format / 互操作约束：// 字段名不能改：…

判定标尺

删掉「对照 Java …」子句后，剩下的句子是否仍说清「为什么这么做」？

• 是 → 保留并改写（去 Java 框）。
• 否（整条只剩对应物命名）→ 删除。

示例对照

坏	好
// GetInfo 获取用户信息（对照 Java SysUserController.getInfo）。	// GetInfo 获取用户信息。
// 请求体是加密的，对齐 Java ApiEncrypt。	// 请求体经 ApiEncrypt 解密后到达此处。
// 失败只记日志：…与 Java 的 try/catch ignored 一致。	// 失败只记日志：注销失败不该阻断写库流程。
// UserApiApp 包级实例。	（删除，var UserApiApp = new(...) 已自解释）

包 / 函数 doc 一句话点明职责即可，复杂逻辑用一两句说清动机。