写好代码注释：团队协作的注释规范

可视化演示

代码注释规范定义了什么时候该写注释、写什么内容、怎么写格式，是团队协作中降低沟通成本的基础。本文讲清楚函数注释... 切换模式查看不同维度。

注释的价值

共享厨房里最怕的不是食材不够，而是老张的秘制酱汁只有他一个人知道。第二天小李接班，看见一锅黑乎乎的卤水，不敢倒也不敢加，只能干等老张回消息。代码注释就是那本“公共菜谱”上的备注，它把一个人脑子里的设计决策，变成所有人都能读到的公共知识。

在 AI 工程里，代码往往比普通业务代码更难懂：数据清洗的规则、特征构造的时机、模型实验的超参数原因，全都藏在代码背后。没有注释，一段三个月前的训练脚本就像一口没贴标签的卤锅——你知道它重要，却不知道它为什么这样。

专业地说，注释是写给人的可执行文档。它不是给解释器看的，而是给下一个维护者、评审者和六个月后的自己看的。好的注释解释 why 与 what-for，而不是复述 what；它记录业务约束、设计权衡、风险点和陷阱。用“信息损耗率”衡量注释的沟通效果：

$$L = \frac{I_{\text{发送}} - I_{\text{接收}}}{I_{\text{发送}}} \times 100\%$$

1. 发送信息量 \(I_{\text{发送}}\)：你想写进注释里的全部设计意图，例如“这里必须先归一化再切分，否则分布偏移”。

$$I_{\text{发送}} = \text{写注释前想表达的信息}$$

2. 接收信息量 \(I_{\text{接收}}\)：队友读完注释后真正理解并记住的信息。

$$I_{\text{接收}} = \text{读注释后准确复述的信息}$$

3. 损耗率 \(L\)：两者差值占发送量的比例，L 越接近 0，说明注释越成功。

$$L = \frac{\text{丢掉的}}{\text{想说的}} \times 100\%$$

所以，注释的价值不是“写了就行”，而是让损耗率尽量低。就像菜谱上写明“老抽提色、冰糖回甘”，下一班厨师不用打电话也能端出一致的味道。

何时写注释

菜谱不会写“拿起锅铲”，但会写“小火慢炖，注意别糊底”。注释也一样，不是给每个语句配解说，而是在容易出错的节点给出提醒。什么时候写？答案是：当代码里藏着“一眼看不穿”的东西时。

复杂业务逻辑、非显然的设计意图、外部系统约束、临时绕过 bug 的 workaround，都是“必须写注释”的候选。判断标准很简单：如果你是第一次读这段代码，会不会想问同事？会，就当场写下来。

比如一个从日期字符串里提取星期的正则，或者一个为了兼容旧接口而保留的兼容分支，如果不写注释，后人很可能会当成无用代码删掉。对 AI 工程来说，特征如何对齐、标签如何清洗，这些业务背景比语法更难从代码本身恢复。可以用“追问率”来辅助判断：

$$K = \frac{N_{\text{追问}}}{N_{\text{秒懂}}} > 1$$

1. 追问次数 \(N_{\text{追问}}\)：新同事阅读代码时皱眉、需要找人的次数。

$$N_{\text{追问}} = \text{需要口头解释的代码块数量}$$

2. 秒懂次数 \(N_{\text{秒懂}}\)：不靠解释就能看懂的代码块数量。

$$N_{\text{秒懂}} = \text{无需注释即可理解的代码块数量}$$

3. 阈值 1：当追问多过秒懂，说明这段代码的隐性知识已超过显性知识，必须用注释补上。

$$K > 1 \Rightarrow \text{该写注释}$$

当小李读菜谱时，只要出现一次“这一步是为什么”的疑问，老张就该在菜谱上补一句。这不是懒惰，而是对后厨效率的投资。

函数注释规范

函数像一道已经出锅的菜：调用者不需要知道火候细节，但需要知道菜名、配料、辣度和副作用。函数注释就是贴在菜盘边的说明卡，让“吃菜的人”不揭锅盖也能安全使用。

函数注释应写在声明上方，内容包含：函数功能、参数含义与类型、返回值、异常，以及一个使用示例。对于 Python，用三引号 docstring；对于 JavaScript/TypeScript，用 JSDoc 标签。JSDoc 用 @param 和 @returns，docstring 用 Args / Returns 段落。注释不是把函数体翻译成文字，而是描述调用契约：传入什么、得到什么、何时抛错。

可以用“入口完备率”检查函数注释是否够用：

$$U = \frac{P_{\text{已注释}}}{P_{\text{参数总数}}} \times 100\%$$

1. 参数总数 \(P_{\text{参数总数}}\)：函数定义里全部入参，包括可选参数。

$$P_{\text{参数总数}} = \text{函数签名中的所有形参}$$

2. 已注释入参 \(P_{\text{已注释}}\)：函数注释中明确写了含义、类型、默认值的参数数量。

$$P_{\text{已注释}} = \text{注释卡片上写明的参数个数}$$

3. 完备率 \(U\)：接近 100% 时，调用者可以完全依据注释拼接参数，不需要翻函数体。

$$U \to 100\% \Rightarrow \text{调用契约清晰}$$

一张说明卡上如果漏写“中辣”，客人咬一口才知道是地狱辣，体验就崩了。函数的每个参数都该被说明，哪怕它看起来显而易见。

行内注释要点

行内注释是锅边便利贴：小、临时、指向明确。老张在炖肉锅边贴张字条“别开盖”，比写一篇文章更有效。行内注释就是这种“别开盖”级别的提醒，只出现在最需要立刻注意的地方。

它主要用在三处：一行看不懂的魔法数字、一段绕来绕去的位运算、一个还没彻底解决的临时修复。注意，行内注释解释的是“为什么这么写”，而不是“这行代码在做什么”——后者是代码自己的职责。如果注释比代码还长，或需要换行才写得下，就应该提升为函数注释或文档字符串。

好注释与坏注释的区别，可以用“为什么”占比来衡量：

$$R = \frac{W_{\text{为什么}}}{Q_{\text{做什么}}}$$

1. 为什么类注释 \(W_{\text{为什么}}\)：解释动机、原因、局限的注释，如“防止浮点溢出，先归一化”。

$$W_{\text{为什么}} = \text{动机型注释条数}$$

2. 做什么类注释 \(Q_{\text{做什么}}\)：机械复述代码行为的注释，如“i++ 将 i 加一”。

$$Q_{\text{做什么}} = \text{复述型注释条数}$$

3. 比值 \(R\)：R 越高，说明行内注释越聚焦于“决策”；如果 R 小于 1，大部分行内注释可以删除。

$$R < 1 \Rightarrow \text{注释多为噪音}$$

便利贴只贴提醒，不贴复读机。如果每行代码后面都贴一张“这是加法”，那后厨早就被废纸淹没了。

文档字符串

如果说行内注释是锅边便利贴，文档字符串就是菜谱的扉页和索引。翻开一本菜谱，先看目录就知道有哪些菜、每道菜的特点；Python 的 docstring 就是模块、类、函数开口处的“扉页文字”，工具能自动把它抽出来生成说明书。

Python 的 docstring 分为几层：模块 docstring 描述模块职责、作者和使用注意事项；类 docstring 描述类的状态与责任；方法 docstring 描述行为、参数、返回值和异常。遵守 PEP 257 能让工具稳定提取。很多团队用 Google style 或 NumPy style 组织 docstring，因为它们分段清晰，既能给人看，也能被 Sphinx 等工具渲染成漂亮文档。

公共 API 的 docstring 尤其重要，因为外部使用者看不到实现，只有这份契约。文档覆盖率是公共 API 的“菜谱完整度”：

$$D = \frac{F_{\text{有文档}}}{F_{\text{函数总数}}} \times 100\%$$

1. 函数总数 \(F_{\text{函数总数}}\)：模块或类中所有公开函数。

$$F_{\text{函数总数}} = \text{需要向调用者暴露的接口数}$$

2. 有文档数 \(F_{\text{有文档}}\)：具备非空 docstring 的函数数量。

$$F_{\text{有文档}} = \text{带文档字符串的接口数}$$

3. 覆盖率 \(D\)：衡量自动生成文档时，多少接口能拿到解释；低于 60% 时文档站会处处空白。

$$D < 60\% \Rightarrow \text{接口文档缺口明显}$$

菜谱目录缺页，客人就不知道还能点什么。公共 API 的 docstring 缺位，外部用户就只能去翻源码猜接口——这比没有菜谱还难受。

主流规范

连锁餐厅的菜谱都有固定模板，因为模板能让员工快速定位“这道菜要多少克盐”。注释的世界里，JSDoc 和 docstring 就是两大主流菜系的模板，它们把“写注释”变成可检查、可自动化的格式。

JSDoc 常用于 JavaScript/TypeScript，核心标签有 @param、@returns、@throws；Python docstring 常见风格有 Google style、NumPy style 和 reST。团队选定一套后，所有成员都按同一套模板写，IDE 才能给出统一的自动提示。除了语言风格，还有团队级模板：比如要求每个函数注释包含“用途、入参、出参、示例”四段；要求提交 PR 时附上注释说明。

风格指南和模板让注释从个人习惯升级为团队契约。可以计算“规范一致性”：

$$S = \frac{C_{\text{符合}}}{C_{\text{检查项}}} \times 100\%$$

1. 检查项总数 \(C_{\text{检查项}}\)：团队规范中定义的注释格式条目，比如行数、标签、段落顺序。

$$C_{\text{检查项}} = \text{规范中可被枚举的格式要求}$$

2. 符合项 \(C_{\text{符合}}\)：实际注释中符合该格式的条目数。

$$C_{\text{符合}} = \text{通过检查的格式要求数}$$

3. 一致性 \(S\)：越高代表代码库越像同一个人写的，可维护成本越低。

$$S \to 100\% \Rightarrow \text{团队风格统一}$$

统一模板不是为了好看，而是让每个厨师拿到任何一道菜谱都能在十秒内找到关键信息。规范带来的是无需思考的熟悉感。

维护防过期

菜谱最怕一件事：菜改良了，菜谱没改。客人点的是新配方，厨师按旧菜谱做，出锅就是事故。代码注释也一样，代码逻辑一变，注释就成了“过期食品”，比没有注释更害人。

维护注释的第一原则是：把注释当代码一样对待。改代码的同时改注释；删除代码时删除相关注释；新增分支时更新分支说明。注释不是一次性投入，而是随代码持续维护的资产。团队可以约定：code review 时把“注释是否与代码一致”作为审查项；发现死注释、误导性注释时要当场删除；TODO/FIXME 必须有负责人和日期，不能无限期挂着。

用“过期率”量化注释债：

$$O = \frac{N_{\text{过期}}}{N_{\text{全部注释}}} \times 100\%$$

1. 全部注释数 \(N_{\text{全部注释}}\)：当前仓库所有注释条目。

$$N_{\text{全部注释}} = \text{仓库中注释的总条数}$$

2. 过期注释 \(N_{\text{过期}}\)：与代码实际行为不一致、会误导读者的注释。

$$N_{\text{过期}} = \text{与代码事实矛盾的注释条数}$$

3. 过期率 \(O\)：O 越高，成员越不敢信任注释，最终大家都不看注释，规范形同虚设。

$$O \to 0\% \Rightarrow \text{注释可信度高}$$

老张改良了卤水配方，就必须同步擦掉“小火炖三小时”，改成“大火烧开转小火九十分钟”。菜谱不更新，再好的手艺也传不下去。

工具与执行

后厨的质检员不可能每天翻遍每本菜谱，但电子系统可以。工具就是那个不知疲倦的质检员：它扫描每一段代码，检查注释格式、docstring 是否存在、覆盖率是否达标，从源头堵住不规范的注释。

常见工具链：JSDoc 配 ESLint 的 jsdoc 插件；Python 配 pydocstyle 检查 docstring 风格；Sphinx、TypeDoc 从注释自动生成文档。团队可以把这些检查接入 CI，PR 未通过规范检查就不允许合并。用工具强制执行的好处是，规范不再依赖个人记忆。新人进来，机器会告诉他“这个函数缺 docstring”；老手也会被统一标准约束。

门禁通过率可以描述 CI 的拦截力度：

$$P = \frac{P_{\text{通过}}}{P_{\text{总PR}}} \times 100\%$$

1. 总 PR 数 \(P_{\text{总PR}}\)：团队一个周期内提交的合并请求总数。

$$P_{\text{总PR}} = \text{Pull Request 的总数量}$$

2. 通过检查的 PR \(P_{\text{通过}}\)：注释规范检查全部通过的请求数。

$$P_{\text{通过}} = \text{通过规范门禁的 PR 数量}$$

3. 通过率 \(P\)：接近 100% 说明注释规范已成为团队习惯，而不是少数人的自觉。

$$P \to 100\% \Rightarrow \text{规范被强制执行}$$

质检员不依赖心情，只依赖规则。工具把“记得写注释”变成“不写注释就过不了门禁”，共享厨房的菜谱才永远不会从某个人脑子里消失。

AI 应用场景

Python 演示

import ast SAMPLE = '''def add(a, b):    """Returns the sum of a and b."""    return a + b def sub(a, b):    return a - b class Calc:    """A tiny calculator."""    def mul(self, a, b):        """Multiplies two numbers."""        return a * b'''  class DocstringStats:    def __init__(self):        self.total = 0        self.doc = 0     def visit_function(self, node):        self.total += 1        if ast.get_docstring(node):            self.doc += 1  def main():    tree = ast.parse(SAMPLE)    stats = DocstringStats()    for node in ast.walk(tree):        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):            stats.visit_function(node)    rate = stats.doc / stats.total * 100    print('函数总数: %d, 有docstring: %d, 覆盖率: %.1f%%' % (stats.total, stats.doc, rate))    return 0 if rate >= 80 else 2  if __name__ == '__main__':    raise SystemExit(main())

1. tree = ast.parse(SAMPLE)把字符串形式的源码解析成语法树，机器才能读到每个函数。
2. ast.walk(tree)深度遍历语法树，找出所有函数定义节点。
3. isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef))同时匹配普通函数和异步函数，确保统计不漏。
4. ast.get_docstring(node)提取函数体首部的字符串字面量，空返回 None。
5. stats.visit_function(node)累计总函数数和有 docstring 函数数。
6. rate = stats.doc / stats.total * 100计算覆盖率，作为门禁判断依据。

常见误区

面试题