用途:在添加、编辑、审查或决定是否保留源码注释时,强制执行“只写 WHY”的注释规范。
主要能力:只保留代码无法读出的理由与背景,例如为何选择某库/API/依赖、为何避开看似更简单的实现、为何需要特定顺序、条件分支、等待、重试或回退、为何优先考虑兼容性、性能、安全或运维约束、为何迎合外部服务、浏览器、Docker、文件格式等特性、为何保留看似多余的处理、以及为避免历史缺陷或回归而做的判断。
禁止内容:不写函数名、变量名、类型、控制结构已表达的处理说明;不逐字解释 if、map、filter、return;不写与代码同粒度的说明;不留仅需与实现同步的注释;不写含糊的 TODO 或意图不明的备忘。已有 WHAT 注释应随周边改动删除或改写为 WHY。
判断步骤:确认该注释是否说明 WHY;若无注释,未来维护者是否会误删、简化或替换;用更好的命名或结构是否更自然。第一条不满足则不写;第三条自然时优先改代码而非加注释。
示例:避免“// 将图像转换为 JPEG”,改为“// HEIC 在浏览器显示不稳定,故在代理侧统一转为 JPEG 返回”;避免“// 无资源 ID 则返回 400”,改为“// 向 Immich API 传递空 ID 会返回 500,故在此规范化为面向用户的输入错误”。
审查处理:发现 WHAT 注释视为删除候选;需要 WHY 却无注释时,除补注释外,也应确认能否通过更清晰的命名或结构解决。
限制:该技能仅约束本仓库源码注释规范,未提供安装命令、平台、收费或价格信息。