跳到正文

我所理解的 JavaScript 最佳实践(10):正确写注释

我所理解的 JavaScript 最佳实践

  1. 使用现代化工具
  2. 尽量去掉只用一次的中间变量
  3. 遍历的起点决定按 ID 取数的顺序
  4. 不用 reduce
  5. 按遍历任务选择循环和数组方法
  6. 异步遍历按任务依赖选择并发或串行
  7. 卫语句让主流程保持平直
  8. 用函数给可复用的业务规则命名
  9. 让顺序无关的代码按名称排列
  10. 正确写注释(当前)
  11. 一行代码只做一件事
  12. 给函数起合适的名字
  13. 用空值合并运算符更好地控制默认值生效逻辑
  14. 用队列串行处理偏好更新,避免修改互相覆盖
  15. 确认弹窗关闭时,让等待中的 Promise 得到结果
  16. 用独立的预期值捕获实现错误
  17. 控制文件行数
  18. 控制函数圈复杂度和认知复杂度
  19. 使用工具函数进行类型判断
  20. 会演进的函数用对象参数
  21. 使用改进的原生 API
  22. 使用模板字符串优化多行文字展示
  23. 用查表取值,用 switch 分派动作
  24. 正确使用纯函数和副作用
  25. 避免数组空位
  26. 把条件写在可选元素和字段旁边
  27. 让独立条件各自表达

我写注释前,会先想下一位读到这段代码的人可能在哪儿停住。我习惯先看函数名和上面的一行说明,知道它负责哪一段,再决定要不要读实现。要是代码里有一个看起来可以删掉的分支,删掉以后却会破坏某种输入,注释就该让人认出那种输入。

注释补上代码里缺的那部分信息

  • 先让名字说清对象和动作。一个业务函数只比较触发复审的字段,就把这个范围体现在函数名里。函数前可以交代哪些变动会触发复审。函数体里的普通赋值和直观表达式留给代码自己说明。
  • 把说明放在做决定的地方。分支的触发条件、某一步必须先执行的原因、兼容路径何时能删,都紧贴对应代码。配置项各自对应不同页面或接口时,把出处写在对应项旁边。模块的开头可以交代整个流程的职责,局部的取舍仍在原地说明。
  • 把调用者需要的约定写在公开入口。类型能告诉调用者传什么、拿到什么,注释还可以说何时生效、会改动谁的状态、什么情况下会抛错。普通 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 历史找回,当前文件只需要给读者看还会执行的路径。

评审里遇到理解成本高的改动,可以让没参与讨论的人试着指出代码的输入前提和失败路径。要是必须把聊天里的背景补一遍才答得出来,就把缺的那句写到最先需要它的地方。