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

{"type":"doc","content":[{"type":"blockquote","content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"本文源于翻译 ","attrs":{}},{"type":"link","attrs":{"href":"https://dev.to/carlillo/clean-code-applied-to-javascript-part-ii-variables-pc","title":"","type":null},"content":[{"type":"text","text":"Clean Code Applied to JavaScript — Part II. Variables","attrs":{}}]}]}],"attrs":{}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"这篇文章是 “代码整洁” 系列中的一篇，这一系列文章都在探讨如何编写 JavaScript 整洁代码。在本系列的文章中，我们将讨论程序员都应知应会的、应用于 JavaScript/TypeScript 语言的代码整洁之道。","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"简介","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"在这篇文章中，我们将介绍书写整洁代码的基本技巧和建议，并重点关注于代码中的最基本的元素 -- ","attrs":{}},{"type":"text","marks":[{"type":"strong","attrs":{}}],"text":"变量","attrs":{}},{"type":"text","text":"。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"本文中所有示例都是用 JavaScript 来实现，但是这些良好的实践适用于任何编程语言，包括 “最接近硬件”（","attrs":{}},{"type":"link","attrs":{"href":"https://en.wikipedia.org/wiki/Close_to_Metal","title":"","type":null},"content":[{"type":"text","text":"CTM","attrs":{}}]},{"type":"text","text":"） 的编程语言。为什么要特别强调这一点呢？曾经和同事讨论过，他们在工作中使用 C 或 Go 语言做开发，但是并不喜欢将这些实践应用于开发中，他们甚至认为在他们使用的编程语言中 “没有人” 会这样做。然后我的回答是，只有行动起来才能有所改变。尽管如此，我们还是对这些实践的优缺点做了较长时间的讨论。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"接下来，我们开始介绍如何将这些技巧应用在程序中的变量上。","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"变量名要名副其实","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"变量的名称必须能够描述出该变量的作用和用途。也就是说，我们不应该用 ","attrs":{}},{"type":"codeinline","content":[{"type":"text","text":"x","attrs":{}}],"attrs":{}},{"type":"text","text":" 或 ","attrs":{}},{"type":"codeinline","content":[{"type":"text","text":"y","attrs":{}}],"attrs":{}},{"type":"text","text":" 这样的名字去作为变量名，除非我们正在开发数学软件，在数学的语境中，这些名字是准确的。在其他的情况下，应该避免使用这种变量名，因为它无法描述出该变量的真实用途，使代码难于理解。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"首先，如果我们调用一个名字为 ","attrs":{}},{"type":"codeinline","content":[{"type":"text","text":"x","attrs":{}}],"attrs":{}},{"type":"text","text":" 的变量，我们能否立刻知道它用来做什么事情吗？不能！","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"其次，我们继续保留名称，并为它添加注释。不过我们为什么要给一个不规范的变量名去添加注释呢? 很显然，这个问题有更简单的解决方案，那就是给变量取一个合适的名称。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"现在有趣的事情来了，父母给孩子起个名字需要多久？与之类似，要找到合适的变量名称，我们同样需要很长时间。但最重要的是，在 IDE 的支持下，我们可以不断地重命名变量，直到找到一个更恰当的名称。选个好名字需要花时间，但磨刀不误砍柴工，简单易懂的名字让我们很轻易的知道发生了什么。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"javascript"},"content":[{"type":"text","text":"const x; // What it is?!\nconst x; // User information\n\n\nconst user;\n","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"变量名可以读出来","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"如果一个变量的名字有意义，最好的一点就是我们能够把它的发音读出来。回到整洁代码的重要实践之一，即生成人类可读的代码，我认为能够读出变量的发音是必要的。因此，在这种场合不应该使用首字母缩略词，即使它们看起来非常的巧妙。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"在选择变量的名称时，另一个错误的行为是删除一个词中某些字母，使用这些缩略语读起来很困难。首先，我们是在用英语编码，而且不是所有的开发者都是讲英语的。因此，我们为什么要把它的名字减少 3 或 4 个字符？这有什么好处呢？代码会被工具（转译器包括其他语言的编译器）操作，最终正确地完成格式化（使用 Prettier）。因此，把不能发音的名字放在一起，只能让我们更费力地去推断变量的用途。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong","attrs":{}}],"text":"请不要让我思考那些不是业务逻辑重点的事情！！","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"看看下面的第一段代码，你可能会推断出该类正在创建的数据类型，但这很考验团队同事之间的默契度。在第二段代码中，它定义了同样的数据，但不需要花费任何脑力就能让人知道变量的用途。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"javascript"},"content":[{"type":"text","text":"class DtaRcrd102 {\n private Date genymdhms;\n private Date modymdhms;\n}\n\n\nclass Customer {\n private Date generationTimestamp;\n private Date modificationTimestamp;\n}\n","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"不要在名称中使用变量的类型","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"在变量名称中使用数据类型作为前缀是一个很古老的做法，现在让我们反思一下这个问题。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"bulletedlist","content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"变量名称中必须要用类型作为前缀吗？","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"每个公司和工程都有各自的前缀规范，那如何去学习和书写这种代码呢？","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"如果我在变量的名称中使用一种编程语言的类型系统，为什么要用它呢？","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"当变量的数据类型发生变化时，比如把 Array 修改为 Map，这种情况怎么处理？","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"这个前缀能给我们带来什么？它是可以发音的吗？","attrs":{}}]}]}],"attrs":{}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"如果我们的语言是类型化的，我们为什么要有这个前缀呢？但是，即使这个语言没有被类型化，就像发生在 JavaScript 中的那样。我们在变量的名称中揭示了一个具体的实现，它将我们与数据的类型相联系。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"也就是说，我们正在将数据类型与业务逻辑关联到了一起。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","marks":[{"type":"strong","attrs":{}}],"text":"这是毫无意义的！","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"恰恰相反，它使变量无法发音，如果我们进行改进（使我们的代码适应新的数据类型），我们就必须重新命名所有的代码。也就是说，","attrs":{}},{"type":"text","marks":[{"type":"strong","attrs":{}}],"text":"这个前缀是噪音","attrs":{}},{"type":"text","text":"。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"看一下变量定义中的两个例子。作为一个开发者，你真的有必要使用这个前缀来理解变量的内容吗？","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"javascript"},"content":[{"type":"text","text":"const aCountries = [];\nconst sName = '';\nconst dAmount = 3.2;\n\n\nconst countries = [];\nconst name = '';\nconst amount = 3.2;\n","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"对同一类型的变量使用相同的词汇表","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"这个建议并不专门针对团队内工作的时候，即使在单独生成代码的时候也会有类似情况发生。尤其是在我们作为软件开发者的职业生涯的开始阶段。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"对同一类型的数据使用相同的词汇表。如果我们需要检索一个用户或客户的信息，我们不能以不同的方式称呼用户或客户。也就是说，不能有时称其为 ","attrs":{}},{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"user","attrs":{}},{"type":"text","text":"，有时称其为 ","attrs":{}},{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"customer","attrs":{}},{"type":"text","text":"，甚至是 ","attrs":{}},{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"client","attrs":{}},{"type":"text","text":" 这个词。更不可取的是，在变量名称上额外再加一个后缀。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"因此，在软件开发中，要对行业术语和名词词汇进行统一的规范或定义。特别是在团队开发时，这个规范或定义尤为重要，避免让一群开发者用不同的名字来指代同一个概念。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"下面的代码就是很好的示例。同一个概念，有三个不同的定义。必须自始至终使用统一的命名，不管是 ","attrs":{}},{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"user","attrs":{}},{"type":"text","text":"、","attrs":{}},{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"customer","attrs":{}},{"type":"text","text":" 还是 ","attrs":{}},{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"client","attrs":{}},{"type":"text","text":"，只能用同一个。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"javascript"},"content":[{"type":"text","text":"getUserInfo();\ngetClientData();\ngetCustomerRecord();\n\n\ngetUser();\n","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"不要添加不需要的上下文","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"在变量名称中没有必要添加类或包的相关上下文。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"在变量名称中添加上下文是很常见的，这样可以知道这个变量位于哪个工作区。事实上，当我们阅读代码时，会很快意识到这是完全没有必要的。在理解代码的过程中，这些不必要的冗余会带来一些干扰。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"在下面的例子中，定义了一个汽车 ","attrs":{}},{"type":"codeinline","content":[{"type":"text","text":"Car","attrs":{}}],"attrs":{}},{"type":"text","text":"，有三个基本属性和一个方法。在变量包含了上下文的情况下，我们可以观察到 ","attrs":{}},{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"car","attrs":{}},{"type":"text","text":" 这个词不断的重复，并且没有任何作用。如果我们去掉 ","attrs":{}},{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"car","attrs":{}},{"type":"text","text":" 这个词（上下文），代码也完全可以被理解；事实上，由于我们去掉了这些噪音，代码会变得更容易理解。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"javascript"},"content":[{"type":"text","text":"const Car = {\n carMake: 'Honda',\n carModel: 'Accord',\n carColor: 'Blue',\n};\n\nfunction paintCar(car) {\n car.carColor = 'Red';\n}\n\n\nconst Car = {\n make: 'Honda',\n model: 'Accord',\n color: 'Blue',\n};\n\nfunction paint(car) {\n car.color = 'Red';\n}\n","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"不要使用魔法数字和字符串","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"在编写代码时，不应该在源代码中直接使用数字或文本字符串，这些通常也被称为魔法数字。这个数字是什么意思？必须要解释这个数字吗？这让我们不得不思考业务逻辑之外的事情。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"因此，这些魔法数字或字符串必须存储在常量中，通过对常量的名称来表达出它们的用途。在业务逻辑层面上，对于那些有意义的数字或文本字符串，如果没有一个确切的名字就会引起噪音。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"下面的例子中，莫名其妙出现的数字 86400000，会让人丈二和尚 -- 摸不着头脑。此外，文本字符串也是危险的，譬如在多次书写 ","attrs":{}},{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"Administrator","attrs":{}},{"type":"text","text":" 过程中，如果某次将其误写为 ","attrs":{}},{"type":"text","marks":[{"type":"italic","attrs":{}}],"text":"Adminitrator","attrs":{}},{"type":"text","text":" 导致代码发生问题，却不易排出错误。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"codeblock","attrs":{"lang":"javascript"},"content":[{"type":"text","text":"// What the heck is 86400000 for?\nsetTimeout(blastOff, 86400000);\nuser.rol = 'Administrator';\n\n\nconst MILLISECONDS_IN_A_DAY = 86400000;\nconst ADMINISTRATOR_ROL = 'Administrator';\n\nsetTimeout(blastOff, MILLISECONDS_IN_A_DAY);\nuser.rol = ADMINISTRATOR_ROL;\n","attrs":{}}]},{"type":"heading","attrs":{"align":null,"level":2},"content":[{"type":"text","text":"结论","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"在我们刚开始成为一名开发人员的时候，我们可能不会注意到变量的名称，因为通常我们刚开始开发脚本或代码的时候都是在独自工作。并且我们的关注点都是如何编写代码，一旦项目被开发出来之后，我们就不会再阅读自己的源代码。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"然而，当我们开发一个需要花费相当长时间维护的软件时，我们就需要阅读和重新读取源代码。这时，合理的命名变量将给我们带来高质量的、整洁的代码。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"在这篇文章中，我们回顾了给变量命名时的一些基本要点。如果你正在学习编程，把它们写下来，因为在未来它们将为你节省许多精力。如果你有一个漫长的职业生涯，你会发现，通过不断地阅读代码，你自然而然地就会得出了这些结论。","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"请记住，我们讨论的要点如下:","attrs":{}}]},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"bulletedlist","content":[{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"变量名要名副其实","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"变量名可以读出来","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"不要在名称中使用变量的类型","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"对同一变量的类型使用相同的词汇","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"不要添加不需要的上下文","attrs":{}}]}]},{"type":"listitem","attrs":{"listStyle":null},"content":[{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"不要使用魔法数字和字符串","attrs":{}}]}]}],"attrs":{}},{"type":"horizontalrule","attrs":{}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null}},{"type":"paragraph","attrs":{"indent":0,"number":0,"align":null,"origin":null},"content":[{"type":"text","text":"关注公众号 “","attrs":{}},{"type":"link","attrs":{"href":"https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f37bc98a8bae45269ca7982cbb0d344a~tplv-k3u1fbpfcp-zoom-1.image","title":"","type":null},"content":[{"type":"text","text":"KooFE前端团队","attrs":{}}]},{"type":"text","text":"” 回复 「JavaScript整洁代码」有机会获得 ","attrs":{}},{"type":"link","attrs":{"href":"https://book.douban.com/subject/4199741/","title":"","type":null},"content":[{"type":"text","text":"代码整洁之道","attrs":{}}]},{"type":"text","text":" 图书一本。","attrs":{}}]}]}