Comments First 是一个面向软件开发者的注释实践技能,核心主张是:注释承载了设计者脑中无法写进代码的信息;没有接口注释就没有真正的抽象,调用方只能去阅读函数体。
用途
该技能可用于三种场合:一是编写新代码时先写接口注释,把注释作为设计探针;二是审计已有代码的注释与文档注释;三是为代码元素选择更精确的名称。
模式 A:新代码,注释先行
先写类或模块的接口注释,说明它提供什么抽象、一个实例代表什么以及它的限制。
接着只写主公共方法的签名和接口注释,函数体留空。
反复迭代这些注释,直到它们同时做到简短与完整。如果一条注释无法既简短又完整,说明设计有问题。此时应修正设计,而不是修改文字。
然后注释关键字段,再开始写函数体。每个新方法都要在其函数体之前先写好注释。
模式 B:审计已有代码
按以下顺序检查:
接口注释应给出调用方可见的行为、每个参数与返回值的精确含义、副作用、错误以及前置条件。调用方应永远不需要阅读函数体。
接口注释中不得包含实现细节。内部实现属于函数体内部。
注释不得重复代码。检验方法:仅凭相邻那一行代码,别人能否写出这条注释?注释用词应与名称不同。
字段与参数要精确:单位、边界是包含还是排除、null 代表什么、由谁释放或关闭、不变量。用名词描述它是什么,而不是代码如何切换它。
实现注释解释一个代码块做什么以及为什么,而不是怎么做。在每个主要阶段或复杂循环之前放一条。
跨模块规则要放在人们能找到的单一位置:大家都编辑的那个枚举,或者一个通过 // See "X" in designNotes 引用的 designNotes 部分。
信息属于代码,而非提交日志。如果未来的读者需要知道“为什么”,就把它写进代码。
维护方面:让每条注释紧挨它所描述的代码,每个事实只记录一次,提交前检查差异中是否有过时注释。
关于命名
先建立一个意象。单独看到这个名字时,读者能否猜出它是什么?长度以 1 至 3 个词为目标。
精确优于笼统。例如用 numActiveIndexlets 而非 count,用 cursorVisible 而非 blinkStatus。布尔值应使用谓词形式。
保持一致。一个概念对应一个名称,一个名称对应一个概念。如果同一事物存在两种类型,就要区分它们,例如 fileBlock 与 diskBlock,最好使用不同的类型。
名称长度随声明与使用之间的距离增长。在只有三行的循环里,i 是可以接受的。
难以取名通常意味着这个东西没有清晰的定义。应当拆分它。
输出
在模式 A 中,输出骨架:注释与签名,不含函数体。在模式 B 中,输出格式为“路径:行号 —— 问题 → 改写后的注释或名称”,并附上注释所暴露出的设计异味清单。
适用场景与限制
该技能适用于需要明确抽象边界、提升代码可读性和可维护性的开发工作。资料未提供其支持的具体编程语言、工具集成方式、安装命令或运行环境;这些信息暂未提供。