如何编写可维护和可读的代码

在软件开发中，编写简洁、易维护且易读的代码对于任何项目的成功都至关重要。组织良好、易于理解且易于修改和扩展的代码不仅能提高开发人员的效率，还能降低引入 bug 和错误的概率。
本文将探讨一些在 JavaScript 和 TypeScript 中编写简洁、易维护且易读代码的最佳实践和技巧，但需要注意的是，这些原则也适用于其他编程语言。

使用有意义的变量名和函数名

编写简洁代码的基本原则之一是使用有意义且描述性的变量名和函数名。精心选择的名称可以极大地提高代码的可读性和可理解性。当其他人阅读你的代码时，他们应该能够快速理解每个变量或函数的用途和功能，而无需大量的注释或额外的文档。

例如，我们来看下面这段使用了命名不规范的变量和函数的代码片段：

let a = 10;
let b = 20;

function f(x, y) {
  let c = x + y;
  if (c > a) {
    return c - b;
  } else {
    return c + b;
  }
}

console.log(f(a, b));

在这段代码中，变量a和b的含义并不明确。同样，函数f 的名称也含糊不清，并且使用了像x、y和c这样晦涩难懂的变量名。这使得我们难以理解该函数的功能以及它与代码其他部分之间的关​​系。

为了提高这段代码的可读性，我们可以先使用更具描述性的变量名来表明它们的用途。例如，我们可以将a重命名为threshold，将b重命名为offset，以便更好地表达它们的含义：

let threshold = 10;
let offset = 20;

function f(x, y) {
  let sum = x + y;
  if (sum > threshold) {
    return sum - offset;
  } else {
    return sum + offset;
  }
}

console.log(f(threshold, offset));

经过这些修改，现在更容易理解这段代码的运行机制。变量threshold和offset已根据其具体作用命名，函数f也已重命名为calculateSumWithThreshold，以便更清晰地表达其用途。此外，变量c也已重命名为sum，更能明确地表明其值。

使用描述性强且有意义的变量和函数名称有助于提高代码的清晰度和可维护性。即使在更复杂的示例中，良好的命名规范也能显著提升代码的可理解性和可维护性。

请使用正确的缩进和格式。

一致的缩进和格式对于提高代码可读性至关重要。格式正确的代码能够增强理解力，使代码库的逻辑结构更容易被理解。它还能促进项目内部的一致性，尤其是在多个开发人员共同开发同一段代码时。

请看下面这段没有正确缩进的代码：

function calculateAverage(numbers){
let sum = 0;
for(let i=0;i<numbers.length;i++){
sum += numbers[i];
}
let average = sum/numbers.length;
return average;
}

如果没有缩进，就很难直观地识别代码的结构和嵌套层级。这会导致混淆，并在理解或修改代码时引入错误。

通过采用一致的缩进，代码会变得更易读、更有结构：

function calculateAverage(numbers) {
  let sum = 0;
  for (let i = 0; i < numbers.length; i++) {
    sum += numbers[i];
  }
  let average = sum / numbers.length;
  return average;
}

格式化后的代码中，每一级缩进都代表着更高一层的嵌套或作用域。它清晰地展现了不同代码块之间的关系，例如循环和条件语句。现在，代码更容易浏览和理解。

除了缩进之外，还应采用一致的格式化规范，例如运算符周围的适当间距、大括号位置的一致性以及相关代码元素的对齐方式。遵循代码风格指南或使用Prettier等代码格式化工具可以帮助保持整个代码库格式的一致性。

保持函数、方法和类简短

“给事物命名时，应使用最常用且最短的名称。”这条原则不仅适用于域名，也适用于软件开发中的各种元素，包括变量、函数、类等等。通过选择更短、更常用的名称，可以显著提高代码的可读性和可理解性。

例如，假设你有一个名为`relinquishSomething`的函数。在这种情况下，选择一个更简短、更常用的替代名称可能更有利。例如，你可以将函数重命名为 ` releaseSomething`。“release”一词比“relinquish”更简短、更常用。你可以使用 Google 或 ChatGPT 搜索同义词，例如“relinquish synonyms”，以找到最简短、最常用的类似词语。

评论和文档

对代码进行注释和文档编写对于确保其清晰度、可维护性和可理解性至关重要。恰当的注释和文档能够提供关于代码用途、行为以及任何注意事项或局限性的宝贵见解。它们可以作为开发人员（包括未来的自己和团队成员）之间的沟通工具，帮助他们更有效地理解和使用代码。

过去，我犯过一个错误，那就是忽略了代码注释和文档编写。我以前总觉得我的代码不会有人看，花时间写注释纯属浪费时间。然而，我很快意识到这种想法是错误的。

代码很少是孤立开发的。项目涉及协作、维护，而且经常需要在不同的开发人员之间传递代码。即使你是唯一的开发人员，你可能在几个月甚至几年后重新审视自己的代码，如果没有适当的文档，理解自己的代码将是一项艰巨的任务。

以下是一些编写代码时添加注释和文档的最佳实践：

• 使用行内注释：在代码中添加注释来解释复杂或不明显的部分。行内注释应该提供额外的上下文和说明，而不是赘述显而易见的内容。

// Calculate the sum of the array
let sum = 0;
for (let i = 0; i < array.length; i++) {
  sum += array[i];
}

• 编写描述性的函数和方法头：每个函数或方法的开头都应该添加描述性注释，概括其用途、输入参数、返回值以及任何副作用。这有助于读者快速理解函数的行为，而无需深入了解实现细节。

/**
 * Calculate the average of an array of numbers.
 * @param {number[]} numbers - The input array of numbers.
 * @returns {number} The average of the numbers.
 */
function calculateAverage(numbers) {
  // Implementation
}

• 编写外部 API 文档：在使用外部 API 或库时，请编写文档说明如何有效使用它们。提供示例，解释输入参数及其预期值，并详细说明响应或预期输出的结构。

• 定期更新注释：请确保您的注释与代码更改保持同步。过时或误导性的注释可能比没有注释更糟糕，因为它们会误导开发人员并造成混乱。

• 编写 README 文件：在项目的根目录中包含一个 README 文件，以提供项目概述、安装说明、使用示例以及与贡献者或用户相关的任何信息。

避免代码重复（DRY 原则）

代码重复，也称为“不要重复自己”（DRY）原则，指的是代码库中存在冗余或重复的代码。重复代码会导致多种问题，包括增加维护成本、降低代码可读性以及引入错误的风险。

您可以考虑以下技巧来避免代码重复并遵循 DRY 原则：

• 提取可重用代码：识别通用功能并创建单独的函数、方法或类

• 利用继承和组合：在面向对象编程中利用继承和组合来实现代码重用。

• 使用库和框架：使用现有工具而不是重新发明功能，以减少重复工作。

• 重构重复代码：定期审查代码，并将通用逻辑提取到可重用的组件中。

避免使用魔法数字和字符串。

魔法数字和魔法字符串是代码库中反复使用的硬编码值，通常缺乏清晰的解释或文档。这些值难以理解和维护，容易导致 bug 和错误。务必为所有魔法数字和魔法字符串声明常量，并在整个代码库中使用它们。这样便于日后修改这些值，并为它们的使用提供上下文。

避免深度嵌套

深度嵌套指的是代码中过多的缩进和嵌套层级。当条件语句、循环或嵌套函数之间存在多层嵌套时，就会出现这种情况。虽然嵌套有时是必要的，但过多的嵌套会使代码难以阅读、理解和维护，还会增加引入 bug 的几率并降低代码性能。

遵循以下技巧，您可以避免代码中出现深度嵌套。首先，将复杂的操作分解成更小、更易于管理的函数或方法，从而简化逻辑。这有助于提高代码的组织性和可读性。其次，定期审查代码，寻找重构或将嵌套代码块提取到独立函数或方法中的机会，从而减少嵌套层级。最后，考虑使用提前返回来处理异常情况或退出条件，这有助于扁平化代码结构，使其更易读。

持续重构

持续重构是编写简洁代码的另一个重要方面。它指的是在不改变代码功能的前提下，对现有代码库进行修改，以改进其设计、结构和可读性。这有助于消除代码异味并减少技术债务。

重构是一个持续的过程，应该融入到你的开发工作流程中。它不应该被视为代码编写完成后才执行的独立任务。重构应该定期进行，以小步迭代的方式推进，以确保代码始终处于良好状态。

删除未使用的代码

你是不是经常忘记从项目中移除未使用的代码？对我来说，这种情况发生的次数比我愿意承认的要多得多。然而，定期审查代码并删除任何不再需要的未使用函数、类或变量至关重要。这样做可以极大地提高代码的可读性并降低复杂性。此外，删除未使用的代码还可以通过减少不必要的处理来提高应用程序的性能。养成识别和删除未使用代码的习惯，可以通过手动代码审查或借助 ESLint 等工具来实现。

概括

编写易于维护和阅读的代码是任何开发人员的基本技能。通过遵循最佳实践和技巧，例如保持一致的编码风格、正确地注释代码以及避免代码重复，您可以极大地提高代码库的质量。

记住，要优先考虑代码的简洁性和可读性，而不是复杂冗长、难以理解和维护的代码。利用自动化工具来帮助识别和删除未使用的代码，从而降低代码库的复杂性。

在多个平台上与我联系