编写整洁的代码有助于你构建可扩展、可维护的软件应用。在这本手册中，@shahancd 解释了什么是整洁代码及其重要性。他还带你了解一些有用的编码模式，并讨论了注释、命名规范、函数、项目结构等内容。https://freecodecamp.org/news/the-clean-code-handbook/…

《整洁代码手册：如何为敏捷软件开发编写更好的代码》

来源：https://www.freecodecamp.org/news/the-clean-code-handbook/

《整洁代码手册：如何为敏捷软件开发编写更好的代码》

构建可扩展的软件应用需要编写简洁的代码，让任何开发者都能轻松理解。在这篇文章中，我将解释并演示什么是整洁代码。然后，我会分享我最喜欢的整洁代码模式，用于构建现代敏捷应用。我不会使用复杂的术语，而是通过简单明了的 JavaScript 示例来聚焦核心概念。直接了当，不废话——这就是我的风格。让我们开始吧。

目录

1. 劣质代码的成本 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-the-cost-of-bad-code)
2. 整洁编码者 vs 混乱编码者 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-clean-coder-vs-messy-coder)
3. AI 救不了你，如果你的代码一团糟 🗑️ (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-ai-cant-save-you-if-your-code-is-a-mess)
4. 构建敏捷应用的 12 个整洁代码设计模式 ⚖️ (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-12-clean-code-design-patterns-for-building-agile-applications)
   • 🌿 使用有意义的名称 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-use-names-that-mean-something)
   • 🔨 保持函数聚焦单一职责 (SRP) (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-keep-functions-laser-focused-srp)
   • 🚪 审慎使用注释 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-use-comments-thoughtfully)
   • ⚡ 编写好注释的最佳实践 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-best-practices-for-writing-good-comments)
   • 🧩 让代码可读 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-make-your-code-readable)
   • 🏌️ 测试你写的所有代码 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-test-everything-you-write)
   • 💉 使用依赖注入 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-use-dependency-injection)
   • 📂 整洁的项目结构 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-clean-project-structures)
   • 🤹♂️ 保持格式一致 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-be-consistent-with-formatting)
   • ✋ 停止硬编码值 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-stop-hardcoding-values)
   • 🤏 保持函数简短 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-keep-functions-short)
   • ⛺ 遵循童子军规则 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-follow-the-boy-scout-rule)
   • 🏟️ 遵循开闭原则 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-follow-the-openclosed-principle)
5. 帮助编写整洁代码的现代最佳实践：总结 🥷 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-modern-best-practices-to-help-you-write-clean-code-a-summary)
6. 维护整洁代码的自动化工具 ⚓ (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-automated-tools-for-maintaining-clean-code)
   • 1️⃣ 静态分析 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-1-static-analysis)
   • 2️⃣ 自动代码格式化 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-2-automated-code-formatting)
   • 3️⃣ 持续集成 (CI) 测试 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-3-continuous-integration-ci-testing)
   • 4️⃣ CI/CD 管道 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-4-cicd-pipelines)
7. 文档在敏捷软件开发中的作用 🚣 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-the-role-of-documentation-in-agile-software-development)
8. 结论 🏁 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-conclusion)
9. 关于整洁代码的常见问题 🧯 (https://www.freecodecamp.org/news/the-clean-code-handbook/#heading-frequently-asked-questions-about-clean-code)

Image of agile software development meme

在敏捷开发中，变化是唯一不变的因素，整洁代码就是你的铠甲。它让你适应性强、行动敏捷，最重要的是，让你掌控全局。事实是：如果你想在软件开发行业立足，编写整洁代码不是可选项。幸运的是，我们人类通过努力和实践能够掌握整洁代码。

劣质代码的成本

Image of cost of messy code vs clean code graph by shahan

解释一下这个堆叠柱状图：在初始开发阶段，劣质代码的变更成本略高于整洁代码。但进入维护和重构阶段后，差距显著扩大，劣质代码的成本几乎是整洁代码的两倍。到了遗留代码阶段，劣质代码的成本达到 100%——此时更新极其昂贵，而整洁代码仍保持在 45% 的可控范围内。截至目前，关于美国低质量软件成本的最新分析是 2022 年由信息与软件质量联盟（cisq.org (http://cisq.org/)）发布的报告。该报告估计，2022 年低质量软件给美国经济造成了至少 2.41 万亿美元的损失，其中技术债务约占 1.52 万亿美元。你可以在此阅读更多内容 (https://www.it-cisq.org/the-cost-of-poor-quality-software-in-the-us-a-2022-report/)。近期的讨论依然强调技术债务对软件质量和业务绩效的重大影响。例如，一项 2024 年的调查 (https://vfunction.com/blog/how-to-manage-technical-debt) 表明，超过 50% 的公司中，技术债务占据其总 IT 预算的四分之一以上。如果不加以解决，这确实会阻碍创新。如你所见，劣质代码无疑是软件开发中成本高昂的问题。

整洁编码者 vs 混乱编码者

下面这张图展示了两类编码者的旅程：

Image of clean code vs bad code graph chart

• ⚠️ 混乱编码者（红线）： 起步快，但崩盘也快。写的代码越多，制造的麻烦也越多。
• ⚡ 整洁编码者（蓝线）： 起步慢，但稳定持续。增长不会停止——反而加速。

🫵 现在，由你决定选择哪条路。

AI 救不了你，如果你的代码一团糟 🗑️

当你写代码遇到困难时，可能会求助 AI。但我要告诉你：如果你的代码一团糟，AI 也救不了你。这就像在沙子上盖房子。短期内也许能立住，但一阵强风或一个大浪过来，它就塌了。记住：AI 只是一个工具。如果你不知道如何编写整洁、可扩展的应用，那你就是在自掘坟墓。如果你连自己写的代码都维护不了，那就麻烦了。我见过太多这样的例子：掌握五种编程语言的开发者，能构建应用、网站、软件，对算法和数据结构了如指掌。但当面对大型项目或别人写的混乱代码时，他们就崩溃了。就像一位航空工程师，设计和制造了自己的飞机，却不知道怎么驾驶——最终撞向自己的代码。我也曾如此……很久以前。我写了数千行代码，结果连自己上周写的内容都看不懂。对我而言那是一片混乱。但后来我意识到——每个开发者都挣扎于此。问题不在于我懂多少，而在于我如何组织和构建我所知道的知识。换句话说，在于掌握编程本身的艺术。我决定跳出这个陷阱。经过五个月的密集工作——每天花四到五个小时编写、设计和研究——我创造了我希望当初编程时就拥有的东西。一本完整的初学者指南：《整洁代码：从零到一》。

cover image of clean code zero to one: from messy code to masterpiece

如果你想了解更多关于这本书的信息，我会在本教程末尾提供所有细节。请继续阅读，学习更多关于编写整洁代码的知识。

构建敏捷应用的 12 个整洁代码设计模式 ⚖️

如果你的代码不遵循这些现代整洁代码设计模式，你可能会埋下一颗定时炸弹。这些模式就是你的工具。掌握它们，享受项目成功的喜悦。让我逐一展示给你。

🌿 使用有意义的名称

将变量或函数命名为b或x毫无帮助。用它们实际含义来命名，以便更容易理解。下面是一个糟糕和好的变量名示例：

// 弱且模糊
let b = 5;

// 强且清晰
let numberOfUsers = 5;

那些使用不清晰名称的人，不想为自己的错误负责。别做那样的人。

Comic showing a bad vs a good variable name, by Shahan

🔨 保持函数聚焦单一职责 (SRP)

一个函数应该只做一件事——并且做得完美。这被称为单一职责原则（SRP）。好的代码就像锤子，只钉一个钉子，而不是钉十个。例如，如果你雇佣一个人包揽公司所有事务——财务、销售、营销、清洁——他很可能惨败，因为他无法专注一件事。代码中的类也是如此。🚧 当一个类或函数做多件事时，就会变成一团乱麻。调试起来就像解一个颠倒的拼图。例如，如果你的类同时处理用户输入和数据库操作，那不是多任务——而是疯狂。拆分开来。一个方法，一个职责。

🔥 我的规则： 代码为你工作。保持它简洁、专注、可控，否则它就会控制你。以下是如何实现：

// 整洁：一件事，一个焦点
function calculateTotal(a, b) {
  return a + b;
}

function logTotal(user, total) {
  console.log(`User: ${user}, Total: ${total}`);
}

// 混乱：试图做所有事
function calculateAndLogTotal(a, b, user) {
  let total = a + b;
  console.log(`User: ${user}, Total: ${total}`);
}

🪧 当你混合任务时，也就混合了混乱。就这么简单。专业开发者中有一句名言：

“代码会自我说话。”

你每次走进房间时，难道还会解释门是什么吗？你的代码也应该如此。注释本身没有错，但如果代码无法独立表达，那你可能就有问题了。

🪧 好的注释应该说明“为什么”，而不是“怎么做或是什么”。如果开发者不理解“怎么做”，那他们很可能也不理解“为什么”。下面是一些好注释和坏注释的简短示例。我还会展示一个真实项目，用于编写整洁注释。

示例 1：坏注释 👎

// 将价格乘以数量来计算总价
const total = price * quantity;

这是一个坏注释，因为它只是重复了代码已经表达的内容。代码price * quantity不言自明，注释没有增加任何有用信息。

好注释：👍

如果代码清晰简单，你就不需要注释。

const total = price * quantity;

Image illustrating unnecessary comment vs “silent comment”, by Shahan

示例 2：坏注释 👎

// 检查用户是否登录
function isUserLoggedIn(session) {
  return !!session.user;
}

这个注释很差，因为它没有解释isUserLoggedIn()存在的原因。它只是解释了发生了什么。但我们已经知道这是一个认证函数。这个注释完全是浪费时间。

好示例 👍

// 用户通过认证后才能访问受保护资源
function isUserLoggedIn(session) {
  return !!session.user;
}

这是一个好注释，因为它解释了为什么这段代码存在。它告诉我们该函数在允许访问敏感应用部分之前检查用户是否已认证。它关注的是大局。

Before: “Check if the user is logged in”. After: “The user is authenticated before accessing protected resources.” By Shahan.

1. 解释“为什么”，而不是“是什么”：注释应解释代码的目的或上下文，而不是代码在做什么。
2. 避免显而易见的注释：不要为代码已经明确的内容写注释。
3. 保持简洁明了：写易于阅读、直接说明目的的简洁注释。
4. 定期更新注释：过时的注释会误导开发者，因此当代码更改时务必更新注释。

真实世界示例（带好注释）🛒

让我们将这些实践应用于一个真实项目：一个大型电商应用。其中一个函数根据订单详情计算运费。以下是完整代码，我会在下面逐一解释每条注释：

// 运费规则：
// - 订单满 100 美元免运费
// - 订单低于 100 美元标准运费（10 美元）
// - 国际订单额外加收 5 美元
function calculateShipping(order) {
  let shippingCost = 0;

  // 检查订单是否符合免运费条件
  if (order.total >= 100) {
    shippingCost = 0; // 免运费
  } else {
    shippingCost = 10; // 标准运费
  }

  // 国际订单额外加收费用
  if (order.isInternational) {
    shippingCost += 5;
  }

  return shippingCost;
}

// 示例用法
const order1 = { total: 120, isInternational: false };
const order2 = { total: 80, isInternational: true };

console.log(calculateShipping(order1)); // 输出: 0
console.log(calculateShipping(order2)); // 输出: 15

在函数开头，我们添加了一条注释来解释运费规则。这使读者无需阅读完整代码就能了解逻辑概览。

// 运费规则：
// - 订单满 100 美元免运费
// - 订单低于 100 美元标准运费（10 美元）
// - 国际订单额外加收 5 美元

然后，第一个条件检查订单总额是否大于等于 100 美元。这里的注释阐明了为什么应用免运费。

// 检查订单是否符合免运费条件
if (order.total >= 100) {
  shippingCost = 0; // 免运费
}

第二个条件对国际订单收取额外费用。注释解释了为什么要增加额外费用。

// 国际订单额外加收费用
if (order.isInternational) {
  shippingCost += 5;
}

为什么这些注释好？ 想象一下你在一个 20 人的开发团队中。六个月后有人阅读calculateShipping函数。没有这些注释，他们可能会浪费时间猜测为什么国际订单有额外费用。好的注释阐明了原因，节省数小时的挫败感。

🧩 让代码可读

如果别人读你的代码感觉像在解谜，那你就已经成了麻烦制造者。证据如下：

// 整洁：读起来像故事
if (isLoggedIn) {
  console.log("Welcome!");
} else {
  console.log("Please log in.");
}

// 混乱：感觉像一团乱麻
if(isLoggedIn){console.log("Welcome!");}else{console.log("Please log in.");}

如果你的代码混乱且难以阅读，它会困扰他人——甚至包括你自己！想象六个月后回来看自己的代码，却感觉像在读一门外语。可读性强的代码节省时间、减少错误，让每个人的生活更轻松。

🍵 为什么 R