我所理解的 JavaScript 最佳实践(10):正确写注释
- 使用现代化工具
- 尽量去掉只用一次的中间变量
- 遍历的起点决定按 ID 取数的顺序
- 不用 reduce
- 按遍历任务选择循环和数组方法
- 异步遍历按任务依赖选择并发或串行
- 卫语句让主流程保持平直
- 用函数给可复用的业务规则命名
- 让顺序无关的代码按名称排列
- 正确写注释(当前)
- 一行代码只做一件事
- 给函数起合适的名字
- 用空值合并运算符更好地控制默认值生效逻辑
- 用队列串行处理偏好更新,避免修改互相覆盖
- 确认弹窗关闭时,让等待中的 Promise 得到结果
- 用独立的预期值捕获实现错误
- 控制文件行数
- 控制函数圈复杂度和认知复杂度
- 使用工具函数进行类型判断
- 会演进的函数用对象参数
- 使用改进的原生 API
- 使用模板字符串优化多行文字展示
- 用查表取值,用 switch 分派动作
- 正确使用纯函数和副作用
- 避免数组空位
- 把条件写在可选元素和字段旁边
- 让独立条件各自表达
我写注释前,会先想下一位读到这段代码的人可能在哪儿停住。我习惯先看函数名和上面的一行说明,知道它负责哪一段,再决定要不要读实现。要是代码里有一个看起来可以删掉的分支,删掉以后却会破坏某种输入,注释就该让人认出那种输入。
注释补上代码里缺的那部分信息
- 先让名字说清对象和动作。一个业务函数只比较触发复审的字段,就把这个范围体现在函数名里。函数前可以交代哪些变动会触发复审。函数体里的普通赋值和直观表达式留给代码自己说明。
- 把说明放在做决定的地方。分支的触发条件、某一步必须先执行的原因、兼容路径何时能删,都紧贴对应代码。配置项各自对应不同页面或接口时,把出处写在对应项旁边。模块的开头可以交代整个流程的职责,局部的取舍仍在原地说明。
- 把调用者需要的约定写在公开入口。类型能告诉调用者传什么、拿到什么,注释还可以说何时生效、会改动谁的状态、什么情况下会抛错。普通 JavaScript 和 TypeScript 实现旁优先用短的
//。公共库需要在编辑器里展示这些约定和用例时,JSDoc 有实际用途。 - 用可以回查的事实解释例外。兼容分支写清受影响的条件、去掉后的结果和已经确认的删除条件。复现、测试或上游 issue 可以随注释提供入口。原因还没有查清时,先记已证实的现象。修改经过可以从提交记录查到。
文件头交代职责,目录 README 交代协作关系
从代码搜索直接跳到 library-worker.ts 时,我想先知道这个文件在哪个进程跑、它负责哪一步。文件头用一句话说明这些信息,接下来就能顺着代码读。
// 在独立线程扫描和更新仓库索引,响应搜索、链接和批注查询。
import { parentPort } from 'node:worker_threads';
如果要查索引为何没更新,就得在多个文件间找入口。目录里的 README.md 可以说明客户端管理工作线程,扫描和查询在工作线程执行,Markdown 和链接的索引规则在哪个模块维护。文件头帮助读者判断「我在看哪一步」,目录 README 帮助读者判断「接下来去哪儿看」。批注偏移量为什么要随节点拆分更新,则仍写在改动偏移量的代码旁。
文件头的形式可以交给 @sheng/project-require-file-header-comment 检查。JS、TS 用普通注释,Vue SFC 在最外层用 <!-- -->,后面空一行。ESLint 能检查配置范围内的文件有没有这段说明,职责写得是否准确仍要对照代码。目录 README 优先放在进程边界和有独立职责的业务目录,写清入口、状态归属和下一步可以打开的文件。
每个函数前写一句职责说明
扫读一个文件时,我会先跳着看定义。函数名 rememberLocation 交代了动作,但我还想知道,调用时会立即更新列表,还是等写盘成功才显示。把这句约定放在函数前,定位保存问题时就知道下一步该去哪儿看。
// 立即更新最近位置,随后将本次列表快照排队写入。
function rememberLocation(location: WorkspaceLocation) {
recent = [location, ...recent.filter(item => item.root !== location.root)].slice(0, 12);
void saveLocations(JSON.stringify(recent)).catch((error: unknown) => console.error('无法保存最近打开的位置', error));
}
局部函数、变量绑定的箭头函数、对象和类的方法也可以这样写。像 filter(item => item.root !== location.root) 这样临时传进去的回调,读它所在的表达式就能知道用途。回调复杂到要单独命名时,就在定义前写一句它负责什么。
一句职责说明可以写结果、范围、副作用或失败条件。比如 Stylus 的 visitProperty 上游注释只复述了方法名。这里更值得记录的是「就地归一化属性的表达式,再返回原属性节点」。知道它会修改原节点,读者才容易理解为什么调用结果没有赋给 prop.expr。
@sheng/ts-require-function-comment 检查定义前有没有紧邻的职责说明。单行优先写 //。公开 API 可以用 JSDoc 首句,再补调用者需要知道的参数约定和失败条件。Lint 能检查说明有没有写,评审时还要确认它讲的是代码实际做的事。
在变量旁写清它代表什么
我读中文比读英文快。在用中文协作的项目里,我习惯先扫定义旁的中文说明,串起这个文件读什么、处理什么、写到哪里。查到具体环节,再顺着英文标识符读实现。
Markdown 渲染工具把脚本自身的文件路径存为 currentFile,上面写着「当前 Markdown 渲染脚本的本地文件路径」。脚本把这个值和命令行入口的路径比较,判断要不要直接执行渲染。比较式里用 currentFile 就够了,扫到那行中文说明时,我能立即分清它指的是渲染脚本,还是用户传进来的 Markdown 文件。
给 for (let i = 0; i < 5; i++) 写「循环 5 次」,读者看一眼条件就能得到同样的信息。如果五轮各处理一个采集批次,值得交代的是每轮处理哪个批次,以及五批这个上限从哪来。
扫一个文件时,我会先看类型说清了哪些概念、函数负责哪些动作、模块顶层保留了哪些状态。即使一个缓存从来没有导出,维护者也要知道它在哪些调用之间共享,什么时候清空。常量的说明可以写单位和边界,可变状态则更适合写所有者、更新时机和空值的含义。
我也用同样的方法读 Vue composable 和 React Hook。比如工作台用两个状态把「正在操作」和「失败原因」交给多个入口使用。看说明就能知道哪个状态用来避免重复触发,哪个会展示给用户。
// 为工作台共享操作状态与失败提示。
export function useWorkbenchStatus() {
// 操作尚未结束时,调用方可以据此阻止重复触发。
const busy = ref(false);
// 当前操作的用户可见失败原因,空字符串表示没有错误提示。
const error = ref('');
return { busy, error };
}
说明和声明紧贴。下一条变量有自己的说明时,空行放到下一段说明的上方。函数体开头可以直接写第一段说明。普通函数、事件回调和循环里的临时变量按实际需要说明,例如解释为什么只截取用户可见的一部分文本。
Pinia 的 Setup Store 也可以这样读。以工作区 Store 为例,workspace 的空字符串表示窗口尚未打开目录,workspacePreferences 在没有保存值时回退到默认设置。只在 Store 内部使用的 workspaceVersion 会在切换工作区或销毁 Store 时递增。索引请求用它判断迟到的结果还能否写回。
@sheng/ts-require-definition-comment 默认检查模块顶层的数据绑定,也检查可识别的 composable、Hook 和 Pinia Setup Store 的直属变量。解构出的多个值可以用一条说明交代共同用途。规则可以补相邻变量说明之间的空行,状态究竟由谁使用仍要对照调用方判断。
组件的每个属性和事件都有自己的说明
组件的 props 和 emits 是调用方能看到的接口。读到 Marker 阅读区的 navigation,类型告诉我它可以是对象或 null。字段注释可以再交代一件事:为什么已经有跳转目标,还要传一个独立的 ID。事件也是一样,saved 的载荷类型是文档快照,调用方还需要知道什么时候能拿它替换手上的版本。
<script setup lang="ts">
// 接收本次跳转请求,并在阅读区可见时恢复布局。
const props = defineProps<{
// 等待执行的跳转,独立 ID 让同一目标可以再次定位。
navigation: { id: number; target: ReadingTarget } | null;
// 阅读纸面是否显示,用于决定能否测量布局和恢复滚动。
visible: boolean;
}>();
// 将导航和已保存的文档交回工作台。
const emit = defineEmits<{
// 请求打开链接目标,可显式指定在新标签打开。
navigate: [target: ReadingTarget, newTab?: boolean];
// 写回成功后交付新快照,替换工作台持有的文档内容。
saved: [snapshot: DocumentSnapshot];
}>();
</script>
把说明写在成员上一行。属性可说明它控制什么、单位是什么,或者空值代表什么。事件可说明什么时候发出、接收方拿到载荷后能做什么。事件元组已经给参数命名时,事件上一条注释就可以一起讲清载荷的用法。外层声明的总注释负责交代这组契约的职责。
@sheng/ts-require-definition-comment 默认检查接口的直属成员,也检查 Vue <script setup> 中 defineProps 和 defineEmits 的内联成员。用 withDefaults 包装属性声明时,说明仍写在各字段旁。写成 defineProps<Props>() 时,按 Props 的声明形式就地写说明。Lint 检查的是成员前是否有紧邻的非空说明,实际触发条件要到调用处和 emit() 处核对。
独立 Vue composable 的私有参数也可以这样读。普通选项对象在实现文件声明为 interface Params,每项说明它提供的状态、动作的调用时机或空值含义。签名只引用 Params,定义注释规则可以在声明处逐项检查。见《会演进的函数用对象参数》。
反常分支旁写出实际触发的输入
复现条件尽量写成可以照做的操作。对解析器,写出哪种合法输入产生了意外节点。对界面,写出哪次用户操作和状态更新撞在一起。即使以后找不到原 issue,这些细节也能帮人复现。
Stylus 把属性值还原为 CSS 关键字
同一个文件里,visitExpression 遇到 Block 节点时会构造一个值为 'block' 的字面量。原注释交代了节点的来源。带块 mixin 的块被用作属性值时,就会走到这里。单看判断式只能看出节点的类型。
在 Stylus #1712 的复现中,blockify() 的 {block} 用来插入调用方传入的声明块,但同一个 mixin 里也有一条普通的 display block。求值时,属性值里的 block 可能拿到同名的块节点,CSS 要的却是关键字 block。修复和回归用例覆盖了这个输入。
// stylus/test/cases/functions.call.mixin.styl:114-120
blockify()
display block
{block}
.red
+blockify()
background red
保留分支时,这个用例会生成 display: block 和 background: #f00。用同一份输入,在 Stylus f2967676 上临时跳过表达式中的转换,输出里出现了空的 display: ;,还多出一对包含背景声明的花括号。对维护者来说,知道 block 是怎么进到属性值里的,才知道删改这段时该跑哪条用例。写在条件旁的注释可以直接带上这个输入。
// 带块 mixin 中的 display block 可能把属性值求值成调用方传入的块节点。
// 这里还原 CSS 关键字 block,避免生成空的 display 声明。见 Stylus #1712。
Vue 在组字期间保留输入框里的文字
Vue #2302 的复现发生在拼音组字期间。输入框已经显示用户键入的字母,绑定的 v-model 却仍是上一次确认的值。此时,如果其他状态让组件重新渲染,更新过程又把旧值写回 input.value,还没选字的内容就被覆盖了。
Vue 在 文本框的更新分支里检查 el.composing。源码注释 avoid clearing unresolved text. #2302 说明提前返回保护的是还没确认的文字,跳过的是向 DOM 回写值。组字结束后,事件处理器会补发一次 input,把最终文字交给绑定值。
Vue 的组合输入测试通过派发组合输入事件对照两条路径。组字期间让组件重新渲染,输入框里的 zhong 保留,模型值仍为空。结束组字时,输入框和模型值都变成「中」。这里的两条路径分别是 DOM 到模型的输入事件,以及模型到 DOM 的更新分支,两边都要识别组字状态。
算法注释写出范围和不变量
碰到下标和边界,我会先写清它指向哪个集合、包不包括端点。尤其是同一个数字还能表示「缺失」时,说明要放在它被写入的位置,读者才知道怎样区分两种含义。
二分查找保留第一个匹配
短循环也可能需要解释做法。比如在升序数组里找第一个大于等于目标的元素。函数名 lowerBound 能说明这是一种边界查找,但光看 right = middle 和 left = middle + 1,还得推一遍才能确定遇到相等值时往哪边走。
// values 按数值升序排列。返回第一个 >= target 的位置,全小于 target 时返回数组长度。
function lowerBound(values, target) {
let left = 0;
let right = values.length;
// left 左边的值都小于 target,right 起的值都大于等于 target。
while (left < right) {
const middle = left + Math.floor((right - left) / 2);
if (values[middle] < target) {
left = middle + 1;
} else {
right = middle;
}
}
return left;
}
输入 [1, 4, 4, 7],目标是 4,结果是下标 1。第一次检查到下标 2 的 4 时,右边界移到 2,还要继续检查左边有没有更早的匹配。循环前的那句注释交代的是每一轮都要保持的条件。以后有人想在相等时直接返回,拿重复值一验就能发现,找到任意一项和找到第一项是两个不同的要求。
算法的名字、输入前提和返回边界可以放在函数入口。需要解释的中间状态就放在用到它的地方,像这里的两端边界。更长的推导可以放进设计文档,代码边上留下足以判断改动是否安全的几句话。
Vue 的调度注释把排序和卸载联系起来
Vue 的调度器也用二分查找确定更新任务的插入位置。队列按组件的创建顺序安排父子更新,同一组件的 flush: 'pre' watcher 排在本组件更新之前。这版实现里,有组件 ID 的普通任务用 id * 2 + 1,同组件的 pre 任务用 id * 2。例如子组件 ID 为 2,它的 pre watcher 和普通更新的排序值分别为 4 和 5。
父组件这轮更新如果会卸载子组件,先处理父组件,就能跳过子组件的 watcher 和更新任务。顺序反过来,马上要卸载的组件可能先执行一次 watcher,发起原本可以省下的请求。Vue 分别测试了 同一 ID 的 pre 任务顺序和 卸载时跳过子组件任务。
Vue 用注释交代映射数组里 0 的含义
Vue 更新带 key 的列表时,要把新位置对应到旧位置。这段映射数组初始全是 0,写入时却用 i + 1。定义旁的注释解释了偏移量。0 表示当前位置没有可复用的旧节点,旧下标又从 0 开始,所以保存前必须先加一。
在 列表移动和替换的测试中,[1, 2, 3, 4, 5] 更新为 [4, 1, 2, 3, 6],映射是 [4, 1, 2, 3, 0]。新列表里的 1 对应旧下标 0,所以记作 1。最后的 6 没有对应的旧节点,保留 0。如果把 i + 1 改成 i,旧列表第一项会和新节点共用 0,处理挂载和移动的分支就会把它当作需要挂载的节点。注释放在数组定义旁,读者能就地知道 number[] 表达不出的约定。
算法的取舍写在实现入口
React 在 reconcileChildrenArray 开头说明了为什么不能从两头同时匹配。新数组可以按下标访问,旧子节点却是沿 sibling 串起来的 Fiber 链。旧 Fiber 没有指向前一个兄弟的引用,拿到末尾也走不回去。一般的可迭代输入也得先收集起来,才能从两头访问。
实际实现先 从头匹配。前向匹配走不下去、两边又都还有节点时,才 把剩余旧节点放进 Map,按键查找能复用的节点。注释还提醒维护者核对 reconcileChildrenIterator。可迭代输入走另一段实现,但采用同一套策略,所以修改一处时也要检查另一处。
注释把执行顺序和可见后果连起来
有些顺序问题要等网络变慢,或两个进程同时工作才会出现。把哪两步可能重叠写在代码旁,维护者就知道该用什么条件检查一次看似简单的改动。
Vite 在新样式请求期间保留旧链接
直接替换样式链接的 href,新 CSS 还没下载完时,页面可能短暂失去样式。Vite 的热更新分支先克隆链接并插在旧链接后面,等新请求有结果再移除旧链接。原注释就放在克隆之前,交代了为什么需要多留一个节点。
// vite/packages/vite/src/client/client.ts:267-270
newLinkTag.addEventListener('load', removeOldEl);
newLinkTag.addEventListener('error', removeOldEl);
outdatedLinkTags.add(el);
el.after(newLinkTag);
把这段替换逻辑放进浏览器,故意延后新 CSS 的响应,页面在等待期间仍保留旧样式,load 后才显示新样式。源码也把 error 交给同一个清理函数。新样式加载失败时,旧链接同样会被移除。注释给出了保留旧链接的动机,失败后的行为可以沿事件处理器核对。
Hexo 预览要隔离两种状态
这个博客的本地预览脚本会在启动时执行 hexo clean,再启动 hexo server。两个命令共用一组参数。build-scripts/dev-server.ts 里的注释分别说明这两个参数保护的状态。--config 加载预览配置,用 public_dir 隔离输出目录。--output 把 Hexo 的数据库和合并配置放进预览自己的目录。
const previewHexoArgs = ['--config', previewConfigFiles, '--output', previewStateDir];
单看变量名,只能知道这是一组预览参数。要判断是否能删掉其中一个,还得知道正式构建也在写文件。如果预览的 clean 指向正式 public/,发布脚本可能刚枚举完待上传的文件,下一步读取时文件就已经被删。只改输出目录时,预览和正式生成仍可能共用根目录的 db.json。原注释放在两项参数的定义旁,交代了它们各自保护的状态和少传一项的后果。
公共 API 的注释写给调用者看
Vue 的 shallowRef 返回持有 value 的引用。调用时更容易踩到的是更新边界。用普通对象创建 shallowRef 后,直接改对象字段不会触发依赖更新,给 .value 换一个新对象则会。源码的 JSDoc 在 @example 中把这两个操作并排展示。
下面把源码里的两个操作放进同一个 watchEffect 示例,观察每次更新后的输出。
import { nextTick, shallowRef, watchEffect } from 'vue';
const state = shallowRef({ count: 1 });
watchEffect(() => console.log(state.value.count)); // 1
state.value.count = 2;
await nextTick(); // 没有新输出
state.value = { count: 2 };
await nextTick(); // 2
把两次更新放在同一个例子里,调用者动手改状态前就能看出哪次会让订阅者重新运行。
能执行的约束交给代码和测试
比如订单接口收到的是数字页码,最小有效值是 1。在函数头写一句「页码从 1 开始」,调用者仍然能传入 0。如果这个值来自外部请求,在入口实际检查范围,就能就地发现错误。
// 从外部输入读取从 1 开始的整数页码,无效输入直接报错。
function readPage(value) {
if (!Number.isSafeInteger(value) || value < 1) {
throw new RangeError('页码必须是从 1 开始的整数');
}
return value;
}
错误消息已经指出输入违反了哪条规则。后面若要把页码换成从 0 开始的数组偏移量,可以在换算处注明两端的编号约定。测试适合覆盖容易被改坏的行为,比如第一页偏移量为 0、页码 0 会报错。这样,校验负责拦住错误输入,测试负责发现约定被意外改动,注释则解释为什么两个地方的编号差一位。
前面的 Stylus 用例也有同样的分工。回归测试能发现 display: block 又变成了空声明,分支旁的注释能让维护者在读到 Block 节点时知道这个用例为什么存在。
订单状态由谁推进、失败后能否重试,常常要看几个模块才能拼出全貌,适合集中写进设计文档。代码旁可以留一句当前分支必须遵守的约定,再指向文档里的完整流程。
改行为时一起检查旁边的注释
重构时,最容易漏掉的是文字里对行为的承诺。假如取消同步原来会等清理结束,后来改成只发出取消信号,旧注释里的「已释放订阅」就会让调用方过早启动下一轮。如果订阅由同步任务在自己的 finally 中释放,调用点的注释可以写清这两步分别在哪里发生。
// 这里只发出取消信号,订阅由同步任务在 finally 中释放。
controller.abort();
审查这类改动时,跟着新调用链核对注释里的动词。检查「提交」指请求已发出还是数据已保存,「取消」指已通知任务还是清理已完成。给 Agent 改代码也是一样。它能看到 abort(),但释放资源的时机要从消费者或测试里确认,单靠补一段流畅的文字解决不了。
写临时兼容时,如果已经知道什么时候能删,就写明要等哪一端升级,或等哪类旧输入退出支持范围,再附上对应的回归用例或 issue。待办如果还说不清哪件事要做、由什么条件触发,留一句 TODO 很难帮助接手的人。已经弃用的实现可以从 Git 历史找回,当前文件只需要给读者看还会执行的路径。
评审里遇到理解成本高的改动,可以让没参与讨论的人试着指出代码的输入前提和失败路径。要是必须把聊天里的背景补一遍才答得出来,就把缺的那句写到最先需要它的地方。