用途:该技能针对源码注释的添加、修改与审查,提供一套轻量准则,帮助注释说明意图而不让代码变得杂乱。
主要能力:
- 判断注释必要性。代码应尽可能自解释;只有在“为什么”不明显、存在非显而易见的决策或约束、需要解释边界情况或临时方案、或需要标记未来工作与已知限制(TODO/FIXME)时才写注释。
- 规定简洁准确的写法。优先单行注释,遵循现有约定与检查规则;每个注释块最多三行;说明意图或约束而非代码在做什么;使用完整思想,不用需要反复阅读的碎片。
- 规定注释位置。把注释放在所描述代码的上方,而非行内(除非解释某一行);让注释贴近对应代码;避免尾随注释把代码推得太靠右。
- 要求注释保持最新。代码变化时更新注释,删除不再适用的注释;没有说明时不要保留被注释掉的代码。
- 明确应注释的内容:原因而非机制、非显而易见决策(临时方案、性能选择、兼容性约束)、边界情况与错误处理理由、带上下文的TODO/FIXME。
- 明确不应注释的内容:显而易见的代码、被注释掉的代码(交给版本历史保存)、重复解释、分隔线或作者标签等噪声。
使用方式:在添加、修改或审查注释时,先按上述标准判断是否需要注释;需要时按“为什么”而非“做什么”的原则撰写,控制在一行优先、最多三行;调整位置使其紧贴目标代码;同步检查并更新或删除过时注释与无说明的注释掉代码。
适用场景:为不明显的代码补充意图说明;审查已有注释的清晰度与准确性;判断某段代码应加注释还是应重构。
限制:不处理语言特定文档语法(如JSDoc、docstrings、Go doc注释),不用于文档生成,也不处理提交信息。常见陷阱包括过度注释、过时注释、注释掉的死代码、缺少上下文的含糊TODO和超过三行的长注释。添加或审查后应核对:每条注释是否解释原因而非行为、是否尽量简短、是否保持在一行(最多三行)、是否仍然准确、明显代码是否没有冗余注释,以及是否可以通过让代码更清晰来替代注释。