跳到正文

我所理解的 JavaScript 最佳实践(12):给函数起合适的名字

我所理解的 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. 让独立条件各自表达

读到 badgeColor(status),我能猜到结果和徽标颜色有关,却还要看函数体才能确认它在做什么。如果它只根据状态选颜色,getBadgeColorByStatus(status) 就把取什么、按什么取交代清楚了。返回值可以叫 badgeColor,调用它的函数则有一个动词。

第八篇讲的是哪些业务规则值得提取成函数。确定要写成函数以后,先看调用方需要知道什么。它会读到一个值、得到一个判断结果、拿到新实例,还是触发一次操作?读同一段业务代码时,我希望顺着名字找到取值和判断的依据,也能认出真正改变状态的那一行。

get 适合读取或按条件取值

如果这段代码只负责根据状态给出颜色,可以把函数写成下面这样。ByStatus 交代了取值依据。当上下文只有一套固定的取值方式,getBadgeColor 已经能读懂时,名字也可以短一点。

function getBadgeColorByStatus(status) {
  if (status === 'copying') {
    return '#fbbc04';
  }

  return status === 'copied' ? '#188038' : '#d93025';
}

const badgeColor = getBadgeColorByStatus('copied');

读值和加载在同一个模块里出现时,两个动词也能交代各自的工作。一个本地 Markdown 审阅工具用 getPreferences(root) 给调用方提供当前仓库的偏好,内部的 loadPreferences() 负责从磁盘加载一次。查不到某个仓库时,getPreferences 会生成默认值并留在内存中。调用方看到的是 await getPreferences(root),磁盘读取和缓存属于这个接口的实际成本。项目里的 get 可以异步,也可以按需填充缓存。要知道一次调用会等待多久、是否写入持久数据,还要看接口的约定。

新写一组接口时,我通常把按条件搜索写成 findDocumentByPath,把发网络请求写成 fetchDocument,把本地文件读取写成 readDocumentFile。loadDocument 可以表示把数据加载进当前工作区,具体来源由加载层决定。找不到时返回 undefined、返回 null,还是抛错,仍由类型和调用约定表达。标准库里也有找不到就返回 undefined 的 get,例如 ECMAScript 的 Map.prototype.get。

工厂函数用 create 表达创建行为

批注需要把一整块正文作为显示范围时,createRangeForBlock(block) 会为传入的正文块创建一个 DOM Range。即使两次传入同一个块,调用方也能分别调整得到的两个范围。输入为空时,函数返回 null。这个工厂函数把创建和初始化封装在一起,create 让调用方预期在成功时会拿到新实例。这里创建的是 DOM 规范中的 Range。

function createRangeForBlock(block: Element | null | undefined) {
  if (!block) {
    return null;
  }

  const range = new Range();
  range.selectNodeContents(block);
  return range;
}

工作台测试里的 createDocumentBridgeOverrides() 会用 vi.fn() 创建一组 mock 并返回。两次调用得到的 mock 各自记录调用。如果把已有的 mock 分别装进两个新对象,两边看到的仍是同一份调用记录。创建函数和读取记录的方式见 Vitest 的 vi.fn() 文档。

buildSnapshot(path, revision) 每次也会返回新对象。调用方要的是由路径、版本和正文组成的数据,用 build 就能说明快照的来源。

按仓库复用索引客户端时,已有客户端就直接交回,缺失时才启动 Worker 并登记。getOrCreateIndexClient(root) 能把复用和创建都写进调用点。只从已有映射里取值的 getWorkspace(id),用 get 就足够。

Lint 可以处理一些有明确证据的写法。@sheng/ts-prefer-factory-function-name 会追踪已知构造器或 vi.fn() 的结果,核对函数有没有把新建的值交给调用方。先搜索正文节点再构造 Range 时,findAnnotationRange() 仍然贴切,因为调用方要找的是批注位置。评审时可以问一句,调用方需要知道这次会创建一个独立实例,还是只需要知道它会得到什么数据、完成什么动作。

is、has、can 和 should 回答不同的问题

这些前缀都可以用来命名返回布尔值的函数。拿上传界面来说,正在上传、选了文件、具备上传条件、这一轮应该自动上传,各自会影响不同的代码。

读到的调用 它回答的问题
isUploadInProgress(upload) 这个任务现在处于上传中吗?
hasSelectedFile(selection) 当前选择里有文件吗?
canUpload(account, workspace) 当前账号在这个工作区具备上传权限吗?
shouldUploadAutomatically(preferences) 根据当前设置,这里应该触发自动上传吗?

can 和 should 放在一起尤其有用。账号可以上传,但用户可能关闭了自动上传。先判断能力,再判断这次是否要自动执行,调用处就能看出两项条件各自负责什么。

if (hasSelectedFile(selection) && canUpload(account, workspace) && shouldUploadAutomatically(preferences)) {
  await uploadSelectedFile(selection);
}

is 还常用于判断输入是否符合某个类型,例如 isCodeTheme(value)。TypeScript 中可以用类型谓词让调用方在 true 分支缩小类型。纯布尔变量和属性按读取方式命名即可,例如 dialogIsVisible 或 canUpload。如果 Vue 的 computed 对模板呈现为 badgeColor 这个值,模板也可以像读取其他属性一样使用它。

处理数据时,用名字说出变化

getInitialForm(profile) 让人以为能读到一份已有的表单。如果每次调用都根据资料字段和默认值构造一个新对象,buildInitialFormFromProfile(profile) 会更贴切。类似地,可以用 parse 表达从文本读出结构,用 format 表达生成给人看的表示,用 normalize 表达统一输入形态。

函数名 调用后得到什么或发生什么
parseSavedPreferences(text) 从文本读出偏好数据,非法输入的处理由接口约定。
normalizeWorkspacePreferences(input) 把不同来源的输入整理成模块内部采用的形态。
formatReadingProgress(progress) 得到可显示的进度文本。
savePreferences(root, preferences) 保存偏好,调用方需要处理失败。
setOrRemoveAttribute(element, name, value) 写入或移除 DOM 属性,两个可能动作都在名字里。

canSave 可以在条件里反复判断,真正提交时才调用 savePreferences。即使保存会返回新数据,调用方也能从 save 看出这次会写入。这种区分也见于 Martin Fowler 的 Command Query Separation。

审查函数名时,可以先只看调用处。把几个候选名字念进那一行,看看读者能否猜对返回值的用途、选择所依据的输入,以及调用是否会改变状态。旧项目里的公开接口已有自己的约定。给新入口命名时,把这次需要读者看见的那项信息写出来就够了。