跳到正文

我所理解的 JavaScript 最佳实践(18):控制函数圈复杂度和认知复杂度

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

有两个函数,里面都做了三次判断。一个把三个判断层层套起来,另一个发现当前条件不满足就返回。给它们设计测试时,要覆盖的几种结果相同。读到嵌套版本最里面的一行时,我还要记得上面三层分别成立了什么。这两种负担,适合用不同的指标看。

两个分数回答不同的问题

ESLint 的 complexity 从 1 开始计算圈复杂度,遇到分支决策就加分。它默认用 classic 口径,上限为 20。短路求值、默认参数、解构默认值和可选链也可能引入分支,可以沿诊断位置检查具体语法。

SonarJS 的 认知复杂度估计读懂控制流需要同时记住多少前提。sonarjs/cognitive-complexity 的实现会给嵌套中的结构性分支额外加分,默认上限为 15。顺序语句即使有很多行,读者通常也只需沿用当前的一套前提。

卫语句减少嵌套,保留判断顺序

下面是一个审阅入口的简化例子。它依次判断草稿是否存在、是否改过、用户是否有权限。每次失败都有自己的返回值。

export function reviewState(draft) {
  if (draft.exists) {
    if (draft.changed) {
      if (draft.allowed) {
        return 'ready';
      }
      return 'forbidden';
    }
    return 'unchanged';
  }
  return 'missing';
}

三个 if 各给圈复杂度加 1,加上初始值,得 4。认知复杂度的三个 if 分别加 1、2、3,得 6。把失败路径提前返回,检查顺序和返回值都能逐项对上。

export function reviewState(draft) {
  if (!draft.exists) {
    return 'missing';
  }
  if (!draft.changed) {
    return 'unchanged';
  }
  if (!draft.allowed) {
    return 'forbidden';
  }
  return 'ready';
}

圈复杂度仍是 4,认知复杂度降到 3。四种结果都要验证。真实代码里的失败分支还可能写审计日志、更新状态或释放资源,改成卫语句时,连这些副作用的顺序也要对照。

一起启用两条规则,从告警回到函数

在已有 ESLint flat config 后追加下面的片段。complexity 由 ESLint 提供,另一条规则需要安装 eslint-plugin-sonarjs。这里只开启 S3776,规则按各自默认上限报告。Vue 项目可以沿用已有的 SFC parser 来检查脚本部分。

import sonarjs from 'eslint-plugin-sonarjs';

export default [
  {
    plugins: { sonarjs },
    rules: {
      complexity: 'warn',
      'sonarjs/cognitive-complexity': 'warn',
    },
  },
];

认知复杂度超限时,我先看深处的条件能否提前确定,或循环体能否抽成一段有独立输入、输出和业务名的操作。圈复杂度超限时,我会检查这些分支是否在做同一类决定。例如四条复制命令只是在选路径格式,可以用一张名称到格式的表,再统一调用复制动作。权限校验、覆盖确认和保存失败则有不同的行为,每条路径都值得保留测试。

分数下降之后,试着从入口走完一次失败路径。调用点能读出判断内容,日志和返回值仍按原来的顺序发生,这次拆分才降低了维护成本。