Clean Code JavaScript 整洁代码指南

项目简介

Clean Code JavaScript 是把 Robert C. Martin 的《Clean Code》中的软件工程原则，适配到 JavaScript 语言的开源指南。它不是一份代码风格规范，而是一份关于如何写出可读、可复用、易重构的 JavaScript 代码的实践手册。

作者在开篇强调：这些只是经验性指导，不必逐条严格执行，但它们凝结了多年集体经验，可以作为评估团队代码质量的参照。

内容结构

项目以「坏例 vs 好例」的代码对照方式组织，主要章节包括：

• 变量：有意义的可发音命名、统一词汇、可搜索命名、解释性变量、避免心智映射、避免冗余上下文、用默认参数替代短路求值
• 函数：参数控制在 2 个以内、函数只做一件事、函数名表达意图、避免副作用、避免重复代码等
• 对象与数据结构：使用 getter/setter、让对象拥有私有成员等
• 类：优先组合而非继承、使用方法链等
• SOLID：单一职责、开闭原则、里氏替换、接口隔离、依赖倒置在 JS 中的体现
• 测试：每个测试一个断言、测试单一概念
• 并发：用 Promise 与 async/await 替代回调
• 错误处理：不要忽略捕获的错误、不要对错误状态做过度处理
• 格式与注释：一致的格式、只注释业务逻辑而非代码表面

示例风格

每个原则都会给出简短的正反示例，例如变量命名：

// 坏例
const yyyymmdstr = moment().format("YYYY/MM/DD");

// 好例
const currentDate = moment().format("YYYY/MM/DD");

又如用默认参数替代短路求值：

// 坏例
function createMicrobrewery(name) {
  const breweryName = name || "Hipster Brew Co.";
}

// 好例
function createMicrobrewery(name = "Hipster Brew Co.") {
  // ...
}

使用建议

• 把它当作代码评审清单：评审时对照相关章节，指出可改进点。
• 把它当作团队共读材料：新人入职时按章节阅读，建立统一的代码质量语言。
• 结合 ESLint 等工具落地：例如用 no-magic-numbers 规则辅助「可搜索命名」原则。
• 注意示例基于较早期 JS 语法，阅读时结合 ES2015+ 与现代工程实践理解。

许可协议

项目采用 MIT 协议，可自由引用、翻译与二次整理。