SuperAPI AI 工具集

comment-code

编程与开发

查看项目

更新于 10-18 13:23

技能介绍

历史版本与核实范围

引用固定历史提交12c48de9d36ef839713792a440c651e22630b770中的完整主指南。发布者于2026-09-06 16:56:40 UTC删除此技能,本页保存删除前父版本。2026-10-18 UTC核对精确文件、Git blob及完整正文,中文为全文翻译;代码示例和原始元数据按原样保留。文档中的安装、授权、设备、清理或发布命令均为历史资料,本站未执行;当前安装与运行效果未实测。原条目仓库、名称、标识、网址、安装命令及安装量保持原值。

发布者历史原文

官方删除记录

完整主指南

编写优秀的代码注释

注释的存在是为了捕捉作者心中所想但无法用代码本身表达的信息。代码机械地陈述发生了什么;注释提供意图、契约、理由、单位、不变式和更高层次的图景。好的注释让第一次阅读代码的人也能理解系统,并让抽象隐藏复杂性。成本很小——通常只占开发时间的一小部分——而且每当有人(包括几周后的原作者)需要阅读或修改代码时,它都会带来回报。

统领一切的一条规则

注释那些从代码中不明显的内容。 在保留任何注释之前,问自己:一个从未见过这段代码的人,仅仅通过阅读旁边的代码就能重建这条注释吗? 如果能,这条注释没有增加任何信息——删除它,或者用确实能增加信息的内容替换它。“明显”意味着对第一次阅读的人来说是明显的,而不是对你。

这个单一的测试消除了大多数糟糕的注释,并激发了大多数好的注释。

不要重复代码

最常见的无价值注释只是以相同的详细程度重述下面那行代码。

i = i + 1          # increment i              ← adds nothing
count = len(items) # get the number of items  ← adds nothing

一个近亲是仅仅重复名称中已有词汇的注释:

// Obtain a normalized resource name from the request.
String[] getNormalizedResourceName(Request req) { ... }

这里唯一不在签名中的词是“from”。这没有告诉读者任何他们无法从声明中读到的信息。修复方法是使用与名称不同的词,这些词解释名称仅暗示的含义:什么是规范化资源名称?返回数组的元素是什么?如有疑问,一个明显的标志是每行代码对应一条注释,且粒度与代码相同。

注释的详细程度与代码不同

与代码处于同一级别的注释会重复代码。有用的注释要么比代码更低(更精确),要么更高(更抽象)。

更低级别的注释增加精确性

在声明——字段、参数、返回值——上最有价值,因为名称和类型留下了真正的问题。填补类型无法说明的内容:

  • 单位——像素?毫秒?字节?
  • 边界——范围是包含还是排除端点?
  • 空值——是否允许 null,它意味着什么?
  • 所有权——对于必须释放/关闭的资源,谁负责?
  • 不变式——始终为真的属性,例如“始终包含至少一个条目。”
// Vague:
uint32_t offset;  // current offset in buffer

// Precise:
// Position in this buffer of the first byte that has not yet
// been returned to the client.
uint32_t offset;

在记录变量时,思考名词,而不是动词:描述它代表什么,而不是各种代码片段如何修改它。叙述“在这里设为 true,在那里重置为 false”的注释反映了代码结构并且会过时;陈述含义的注释(“true 表示自上次重置计时器以来已收到心跳”)更短、更稳定,并让读者推断操作。

更高级别的注释增强直觉

这些注释省略细节以传达整体意图——代码用于什么以及它如何适应周围的方法。常见于方法内的块、循环和接口注释。

// Too low-level — partly repeats the conditions below:
// If there is a LOADING rpc with the same session whose last
// hash is smaller than the current one, use that rpc.

// Higher-level — states the purpose:
// Try to append this key hash to an existing, not-yet-sent RPC
// bound for the right server.

有了高级版本,读者可以预测循环所做的几乎一切,并可以判断代码是否正确——这是细节重复的注释永远无法实现的。更高级别的注释更难写,因为它们需要从细节中退一步。问:这段代码试图做什么?解释这一切的最简单的东西是什么?关于它最重要的事情是什么?

一个特别有用的高级形式是**“我们如何到达这里”**——块或方法运行的条件,特别是对于只在异常情况下执行的代码。

注释类别——以及哪些最重要

类别 位置 优先级
接口 紧接在类/方法/函数声明之前的块;定义抽象 最高
数据结构成员 紧邻字段/变量声明 最高
实现 方法体内部 通常不必要
跨模块 描述跨越模块边界的依赖关系 罕见但关键

每个类都应该有一个接口注释,每个类变量一个注释,每个方法一个接口注释。偶尔有些声明本身太明显(一个简单的 getter/setter),无法添加任何有用的内容——但这种情况很少见,而且为所有内容添加注释比每次斟酌更划算。

接口注释定义抽象

接口文档是某人使用类或方法而无需阅读其主体所需的内容。将其与实现细节严格分开。

对于类: 描述它提供的抽象,每个实例代表什么,以及用户必须知道的任何限制(例如“非并发安全”)。

对于方法,涵盖:

  • 一两句话说明调用者所感知的行为(抽象)。
  • 每个参数和返回值,精确地——包括参数之间的约束和依赖关系。
  • 副作用——任何影响未来行为且不是返回值的后果(修改内部状态、写入文件)。
  • 它可能抛出的异常。
  • 调用者必须首先满足的前置条件(尽量减少这些条件,但记录任何仍然存在的条件)。
/*
 * Copy a range of bytes from this buffer to an external location.
 *
 * offset: index of the first byte to copy.
 * length: number of bytes to copy.
 * dest:   destination; must have room for at least `length` bytes.
 *
 * Returns the number of bytes actually copied, which is less than
 * `length` if the range extends past the end of the buffer, and 0
 * if the range and the buffer do not overlap at all.
 */
uint32_t Buffer::copy(uint32_t offset, uint32_t length, void* dest);

读者永远不需要打开方法体就能正确调用它,而注释对副本如何实现只字不提。

危险信号:实现细节泄漏到接口中

如果一个方法的接口注释必须描述其内部工作原理,那是一个警告信号——通常表明该方法很浅(其接口几乎与其实现一样复杂)。将如何移到方法体内部,在那里它与契约清晰分离。用户永远不需要的东西——私有配置参数、内部 RPC 的名称、内部数据结构、不可见的恢复——不属于接口注释。

实现注释:做什么和为什么,而不是如何做

大多数方法足够短,不需要实现注释。当方法很长时,通过在更高层次上说明每个主要块完成什么来帮助读者:

// Phase 1: scan active RPCs to see if any have completed.

对于不简单的循环,描述一次迭代做什么:

// Each iteration extracts one request from the request message,
// increments the matching object, and appends a response.

当为什么不明显时,也要注释:一个棘手的变通方法、一个硬件怪癖,或一个必要性不明显的错误修复。对于被跟踪的错误,指向问题而不是重述它:

// Fixes RAM-436: device-driver crash on Linux 2.4.x.

只有当重要局部变量的使用分散在很大的跨度上时才注释它们;如果每次使用都在几行内可见并且名称很好,就让代码说话。

跨模块注释

有些设计决策跨越多个类(一个协议同时涉及发送方和接收方;一个错误码需要在许多文件中编辑)。这些是微妙且容易出错的,因此需要文档——但困难的部分是把它放在开发人员会找到的地方。

  • 如果有一个每个人都必须触及的自然中心点(例如所有更改都通过的枚举),将横切笔记放在那里,列出所有其他必须更改的地方。
  • 如果没有明显的位置,一个带有清晰标记部分的中央 designNotes 文件效果很好:保留一个权威副本,并从每个相关位置留下一个简短的指针(// See "Zombies" in designNotes)。权衡是,远离代码的笔记更难保持最新——但一个可找到的单一副本胜过重复或埋没的文档。

避免在许多地方重复相同的解释;重复是文档过时的原因。

保持注释新鲜

注释过时的程度只与代码变化的程度成正比,而大型代码更改的成本已经超过了匹配的注释编辑。两个习惯可以保持小幅度漂移:不要重复文档,并且将每条注释放在它所描述的代码旁边。代码审查是发现过时注释的自然场所。

编写或修订注释时的工作流程

  1. 编写注释,然后应用测试:第一次阅读的人仅从相邻代码就能产生这条注释吗? 如果是,重写或删除。
  2. 对于声明,添加类型省略的精确性(单位、边界、空值含义、所有权、不变式)。描述它代表什么,而不是如何改变。
  3. 对于方法/类,首先编写接口注释——行为、参数、返回值、副作用、异常、前置条件——将实现细节排除在外。
  4. 在长方法内部,在更高层次上标记主要块和复杂循环,并解释任何不明显的为什么。
  5. 使用与实体名称不同的词语;追求高于或低于代码的详细程度,绝不要相同级别。
  6. 如果你无法在不描述实现的情况下编写接口注释,将其视为设计异味,而不仅仅是写作问题。

原始元数据

name: comment-code
description: Write clear, useful in-code comments and documentation that capture what the code cannot say for itself. Use this skill whenever writing or revising comments, docstrings, interface/API documentation, function or class headers, or inline explanations — and whenever reviewing code for comment quality or being asked to "document," "add comments," "explain in comments," or improve existing comments. Apply it even when the request only mentions writing the code, since fresh code is the moment to document it well.