我所理解的 JavaScript 最佳实践(12):给函数起合适的名字
- 使用现代化工具
- 尽量去掉只用一次的中间变量
- 遍历的起点决定按 ID 取数的顺序
- 不用 reduce
- 按遍历任务选择循环和数组方法
- 异步遍历按任务依赖选择并发或串行
- 卫语句让主流程保持平直
- 用函数给可复用的业务规则命名
- 让顺序无关的代码按名称排列
- 正确写注释
- 一行代码只做一件事
- 给函数起合适的名字(当前)
- 用空值合并运算符更好地控制默认值生效逻辑
- 用队列串行处理偏好更新,避免修改互相覆盖
- 确认弹窗关闭时,让等待中的 Promise 得到结果
- 用独立的预期值捕获实现错误
- 控制文件行数
- 控制函数圈复杂度和认知复杂度
- 使用工具函数进行类型判断
- 会演进的函数用对象参数
- 使用改进的原生 API
- 使用模板字符串优化多行文字展示
- 用查表取值,用 switch 分派动作
- 正确使用纯函数和副作用
- 避免数组空位
- 把条件写在可选元素和字段旁边
- 让独立条件各自表达
读到 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。
审查函数名时,可以先只看调用处。把几个候选名字念进那一行,看看读者能否猜对返回值的用途、选择所依据的输入,以及调用是否会改变状态。旧项目里的公开接口已有自己的约定。给新入口命名时,把这次需要读者看见的那项信息写出来就够了。