技术英语 / 系统课时

为代码注释补足设计意图

为代码注释补足设计意图

好的英文注释不复述代码,而是保存代码本身看不出来的原因:为什么存在这个限制、为什么不能采用更直观的写法、哪个边界必须维持,以及临时方案何时可以删除。重点是记录设计意图,而不是逐行翻译实现。

学习目标

  • 判断哪些信息值得写进英文代码注释
  • 用简短句子记录约束、兼容原因和边界条件
  • 避免把变量名、条件表达式和函数调用重新翻译一遍

注释回答代码无法回答的问题

看到 retryCount++ 时,读者已经知道计数器增加了,因此 Increment retry count. 没有提供新信息。真正值得记录的是为什么存在重试上限、为什么某种输入必须特殊处理,或为什么不能删除一段看似多余的逻辑。

判断一条注释是否有价值,可以问:如果删掉它,只读实现和测试,后来维护者还能可靠推断出这项约束吗?如果答案是否定的,就值得保留。

常见的高价值内容包括兼容旧系统的原因、外部协议限制、非显然的边界条件、性能或并发取舍,以及带有删除条件的临时方案。

把 What 改成 Why

下面的 JavaScript 可以直接运行。注释没有解释 Math.min 在做什么,而是说明为什么上限必须低于某个值。

js
function normalizeRetryDelay(delayMs) {
  // Keep the value below 32767 ms because the legacy worker stores it
  // in a signed 16-bit field before scheduling the retry.
  return Math.min(delayMs, 30000);
}

console.log(normalizeRetryDelay(45000));

预期输出

text
30000

如果只写 Limit the retry delay to 30000.,读者仍不知道为什么是 30000,也不知道以后能不能改。当前注释保存了真正不可见的上下文:限制来自旧 worker 的存储格式,因此迁移掉该依赖后,这个上限才有重新评估的依据。

优先记录约束与边界

边界条件往往比正常路径更需要注释。例如某段代码故意使用严格小于而不是小于等于,原因来自协议定义,就可以写 The upper bound is exclusive according to the protocol.。这类句子说明了条件不能随意“修正”。

兼容性注释也应指出对象和原因。相比 Workaround for old browsers.,Keep this fallback for Safari 15, which does not support the required API. 更容易验证,也更容易在未来删除。

临时方案必须带退出条件

TODO、workaround 和兼容分支最容易永久滞留。只写 Temporary workaround. 几个月后几乎没有价值,因为没人知道它在等什么变化。

更好的写法应说明依赖条件,例如 Remove this fallback after the v1 API is retired.,或者 TODO: replace this polling loop when the SDK exposes completion events.。如果项目有 issue 编号,可以同时引用真实编号,让后续维护者找到讨论背景。

注释要和实现一起维护

注释最大的风险不是少,而是过期。修改实现时,应同时检查附近解释 Why 的注释是否仍成立。尤其是数字限制、兼容版本和临时方案,一旦外部条件改变,旧注释可能继续误导后来者。

最终可以用一个简单标准判断:代码负责说明“怎么做”,注释负责保存“为什么必须这样做”。当一条英文注释只是把下一行代码换成自然语言时,通常应该删除;当它保存了约束来源、设计取舍或退出条件时,它才真正降低了未来维护成本。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

为代码注释补足设计意图

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通