【译】JavaScript 代码整洁之道-变量篇-技术圈

本文源于翻译 Clean Code Applied to JavaScript — Part II. Variables

这篇文章是 “代码整洁” 系列中的一篇，这一系列文章都在探讨如何编写 JavaScript 整洁代码。在本系列的文章中，我们将讨论程序员都应知应会的、应用于 JavaScript/TypeScript 语言的代码整洁之道。

简介

在这篇文章中，我们将介绍书写整洁代码的基本技巧和建议，并重点关注于代码中的最基本的元素 -- 变量。

本文中所有示例都是用 JavaScript 来实现，但是这些良好的实践适用于任何编程语言，包括 “最接近硬件”（CTM）的编程语言。为什么要特别强调这一点呢？曾经和同事讨论过，他们在工作中使用 C 或 Go 语言做开发，但是并不喜欢将这些实践应用于开发中，他们甚至认为在他们使用的编程语言中 “没有人” 会这样做。然后我的回答是，只有行动起来才能有所改变。尽管如此，我们还是对这些实践的优缺点做了较长时间的讨论。

接下来，我们开始介绍如何将这些技巧应用在程序中的变量上。

变量名要名副其实

变量的名称必须能够描述出该变量的作用和用途。也就是说，我们不应该用 x 或 y 这样的名字去作为变量名，除非我们正在开发数学软件，在数学的语境中，这些名字是准确的。在其他的情况下，应该避免使用这种变量名，因为它无法描述出该变量的真实用途，使代码难于理解。

首先，如果我们调用一个名字为 x 的变量，我们能否立刻知道它用来做什么事情吗？不能！

其次，我们继续保留名称，并为它添加注释。不过我们为什么要给一个不规范的变量名去添加注释呢? 很显然，这个问题有更简单的解决方案，那就是给变量取一个合适的名称。

现在有趣的事情来了，父母给孩子起个名字需要多久？与之类似，要找到合适的变量名称，我们同样需要很长时间。但最重要的是，在 IDE 的支持下，我们可以不断地重命名变量，直到找到一个更恰当的名称。选个好名字需要花时间，但磨刀不误砍柴工，简单易懂的名字让我们很轻易的知道发生了什么。

const x; // What it is?!
const x; // User information


const user;

变量名可以读出来

如果一个变量的名字有意义，最好的一点就是我们能够把它的发音读出来。回到整洁代码的重要实践之一，即生成人类可读的代码，我认为能够读出变量的发音是必要的。因此，在这种场合不应该使用首字母缩略词，即使它们看起来非常的巧妙。

在选择变量的名称时，另一个错误的行为是删除一个词中某些字母，使用这些缩略语读起来很困难。首先，我们是在用英语编码，而且不是所有的开发者都是讲英语的。因此，我们为什么要把它的名字减少 3 或 4 个字符？这有什么好处呢？代码会被工具（转译器包括其他语言的编译器）操作，最终正确地完成格式化（使用 Prettier）。因此，把不能发音的名字放在一起，只能让我们更费力地去推断变量的用途。

请不要让我思考那些不是业务逻辑重点的事情！！

看看下面的第一段代码，你可能会推断出该类正在创建的数据类型，但这很考验团队同事之间的默契度。在第二段代码中，它定义了同样的数据，但不需要花费任何脑力就能让人知道变量的用途。

class DtaRcrd102 {
  private Date genymdhms;
  private Date modymdhms;
}


class Customer {
  private Date generationTimestamp;
  private Date modificationTimestamp;
}

不要在名称中使用变量的类型

在变量名称中使用数据类型作为前缀是一个很古老的做法，现在让我们反思一下这个问题。

变量名称中必须要用类型作为前缀吗？
每个公司和工程都有各自的前缀规范，那如何去学习和书写这种代码呢？
如果我在变量的名称中使用一种编程语言的类型系统，为什么要用它呢？
当变量的数据类型发生变化时，比如把 Array 修改为 Map，这种情况怎么处理？
这个前缀能给我们带来什么？它是可以发音的吗？

如果我们的语言是类型化的，我们为什么要有这个前缀呢？但是，即使这个语言没有被类型化，就像发生在 JavaScript 中的那样。我们在变量的名称中揭示了一个具体的实现，它将我们与数据的类型相联系。

也就是说，我们正在将数据类型与业务逻辑关联到了一起。

这是毫无意义的！

恰恰相反，它使变量无法发音，如果我们进行改进（使我们的代码适应新的数据类型），我们就必须重新命名所有的代码。也就是说，这个前缀是噪音。

看一下变量定义中的两个例子。作为一个开发者，你真的有必要使用这个前缀来理解变量的内容吗？

const aCountries = [];
const sName = '';
const dAmount = 3.2;


const countries = [];
const name = '';
const amount = 3.2;

对同一类型的变量使用相同的词汇表

这个建议并不专门针对团队内工作的时候，即使在单独生成代码的时候也会有类似情况发生。尤其是在我们作为软件开发者的职业生涯的开始阶段。

对同一类型的数据使用相同的词汇表。如果我们需要检索一个用户或客户的信息，我们不能以不同的方式称呼用户或客户。也就是说，不能有时称其为 user，有时称其为 customer，甚至是 client 这个词。更不可取的是，在变量名称上额外再加一个后缀。

因此，在软件开发中，要对行业术语和名词词汇进行统一的规范或定义。特别是在团队开发时，这个规范或定义尤为重要，避免让一群开发者用不同的名字来指代同一个概念。

下面的代码就是很好的示例。同一个概念，有三个不同的定义。必须自始至终使用统一的命名，不管是 user、customer 还是 client，只能用同一个。

getUserInfo();
getClientData();
getCustomerRecord();


getUser();

不要添加不需要的上下文

在变量名称中没有必要添加类或包的相关上下文。

在变量名称中添加上下文是很常见的，这样可以知道这个变量位于哪个工作区。事实上，当我们阅读代码时，会很快意识到这是完全没有必要的。在理解代码的过程中，这些不必要的冗余会带来一些干扰。

在下面的例子中，定义了一个汽车 Car，有三个基本属性和一个方法。在变量包含了上下文的情况下，我们可以观察到 car 这个词不断的重复，并且没有任何作用。如果我们去掉 car 这个词（上下文），代码也完全可以被理解；事实上，由于我们去掉了这些噪音，代码会变得更容易理解。

const Car = {
  carMake: 'Honda',
  carModel: 'Accord',
  carColor: 'Blue',
};

function paintCar(car) {
  car.carColor = 'Red';
}


const Car = {
  make: 'Honda',
  model: 'Accord',
  color: 'Blue',
};

function paint(car) {
  car.color = 'Red';
}

不要使用魔法数字和字符串

在编写代码时，不应该在源代码中直接使用数字或文本字符串，这些通常也被称为魔法数字。这个数字是什么意思？必须要解释这个数字吗？这让我们不得不思考业务逻辑之外的事情。

因此，这些魔法数字或字符串必须存储在常量中，通过对常量的名称来表达出它们的用途。在业务逻辑层面上，对于那些有意义的数字或文本字符串，如果没有一个确切的名字就会引起噪音。

下面的例子中，莫名其妙出现的数字 86400000，会让人丈二和尚 -- 摸不着头脑。此外，文本字符串也是危险的，譬如在多次书写 Administrator 过程中，如果某次将其误写为 Adminitrator 导致代码发生问题，却不易排出错误。

// What the heck is 86400000 for?
setTimeout(blastOff, 86400000);
user.rol = 'Administrator';


const MILLISECONDS_IN_A_DAY = 86400000;
const ADMINISTRATOR_ROL = 'Administrator';

setTimeout(blastOff, MILLISECONDS_IN_A_DAY);
user.rol = ADMINISTRATOR_ROL;

结论

在我们刚开始成为一名开发人员的时候，我们可能不会注意到变量的名称，因为通常我们刚开始开发脚本或代码的时候都是在独自工作。并且我们的关注点都是如何编写代码，一旦项目被开发出来之后，我们就不会再阅读自己的源代码。

然而，当我们开发一个需要花费相当长时间维护的软件时，我们就需要阅读和重新读取源代码。这时，合理的命名变量将给我们带来高质量的、整洁的代码。

在这篇文章中，我们回顾了给变量命名时的一些基本要点。如果你正在学习编程，把它们写下来，因为在未来它们将为你节省许多精力。如果你有一个漫长的职业生涯，你会发现，通过不断地阅读代码，你自然而然地就会得出了这些结论。

请记住，我们讨论的要点如下:

变量名要名副其实
变量名可以读出来
不要在名称中使用变量的类型
对同一变量的类型使用相同的词汇
不要添加不需要的上下文
不要使用魔法数字和字符串

翻译：李想