写出整洁的 JavaScript 代码

前言

每个人写代码风格不一样,但本文给出了十个不同正反例说明,大家可以多参考,但不一定要遵守。本文由@alivebao授权分享,较长多图,大家可以慢慢看。

正文从这开始~

介绍

作者根据Robert C. Martin《代码整洁之道》总结了适用于JavaScript的软件工程原则《Clean Code JavaScript》。

本文是对其的翻译。

不必严格遵守本文的所有原则,有时少遵守一些效果可能会更好,具体应根据实际情况决定。这是根据《代码整洁之道》作者多年经验整理的代码优化建议,但也仅仅只是一份建议。

软件工程已经发展了50多年,至今仍在不断前进。现在,把这些原则当作试金石,尝试将他们作为团队代码质量考核的标准之一吧。

最后你需要知道的是,这些东西不会让你立刻变成一个优秀的工程师,长期奉行他们也并不意味着你能够高枕无忧不再犯错。千里之行,始于足下。我们需要时常和同行们进行代码评审,不断优化自己的代码。不要惧怕改善代码质量所需付出的努力,加油。

变量

使用有意义,可读性好的变量名

反例:

正例:

使用ES6的const定义常量

反例中使用"var"定义的"常量"是可变的。

在声明一个常量时,该常量在整个程序中都应该是不可变的。

反例:

正例:

对功能类似的变量名采用统一的命名风格

反例:

正例:

使用易于检索名称

我们需要阅读的代码远比自己写的要多,使代码拥有良好的可读性且易于检索非常重要。阅读变量名晦涩难懂的代码对读者来说是一种相当糟糕的体验。 让你的变量名易于检索。

反例:

正例:

使用说明变量(即有意义的变量名)

反例:

正例:

不要绕太多的弯子

显式优于隐式。

反例:

正例:

避免重复的描述

当类/对象名已经有意义时,对其变量进行命名不需要再次重复。

反例:

正例:

避免无意义的条件判断

反例:

正例:

函数

函数参数 (理想情况下应不超过2个)

限制函数参数数量很有必要,这么做使得在测试函数时更加轻松。过多的参数将导致难以采用有效的测试用例对函数的各个参数进行测试。

应避免三个以上参数的函数。通常情况下,参数超过两个意味着函数功能过于复杂,这时需要重新优化你的函数。当确实需要多个参数时,大多情况下可以考虑这些参数封装成一个对象。

JS定义对象非常方便,当需要多个参数时,可以使用一个对象进行替代。

反例:

正例:

函数功能的单一性

这是软件功能中最重要的原则之一。

功能不单一的函数将导致难以重构、测试和理解。功能单一的函数易于重构,并使代码更加干净。

反例:

正例:

函数名应明确表明其功能

反例:

正例:

函数应该只做一层抽象

当函数的需要的抽象多余一层时通常意味着函数功能过于复杂,需将其进行分解以提高其可重用性和可测试性。

反例:

正例:

移除重复的代码

永远、永远、永远不要在任何循环下有重复的代码。

这种做法毫无意义且潜在危险极大。重复的代码意味着逻辑变化时需要对不止一处进行修改。JS弱类型的特点使得函数拥有更强的普适性。好好利用这一优点吧。

反例:

正例:

采用默认参数精简代码

反例:

正例:

使用Object.assign设置默认对象

反例:

正例:

不要使用标记(Flag)作为函数参数

这通常意味着函数的功能的单一性已经被破坏。此时应考虑对函数进行再次划分。

反例:

正例:

避免副作用

当函数产生了除了“接受一个值并返回一个结果”之外的行为时,称该函数产生了副作用。比如写文件、修改全局变量或将你的钱全转给了一个陌生人等。

程序在某些情况下确实需要副作用这一行为,如先前例子中的写文件。这时应该将这些功能集中在一起,不要用多个函数/类修改某个文件。用且只用一个service完成这一需求。

反例:

正例:

不要写全局函数

在JS中污染全局是一个非常不好的实践,这么做可能和其他库起冲突,且调用你的API的用户在实际环境中得到一个exception前对这一情况是一无所知的。

想象以下例子:如果你想扩展JS中的Array,为其添加一个diff函数显示两个数组间的差异,此时应如何去做?你可以将diff写入Array.prototype,但这么做会和其他有类似需求的库造成冲突。如果另一个库对diff的需求为比较一个数组中收尾元素间的差异呢?

使用ES6中的class对全局的Array做简单的扩展显然是一个更棒的选择。

反例:

正例:

采用函数式编程

函数式的编程具有更干净且便于测试的特点。尽可能的使用这种风格吧。

反例:

正例:

封装判断条件

反例:

正例:

避免“否定情况”的判断

反例:

正例:

避免条件判断

这看起来似乎不太可能。

大多人听到这的第一反应是:“怎么可能不用if完成其他功能呢?”许多情况下通过使用多态(polymorphism)可以达到同样的目的。

第二个问题在于采用这种方式的原因是什么。答案是我们之前提到过的:保持函数功能的单一性。

反例:

正例:

避免类型判断(part 1)

JS是弱类型语言,这意味着函数可接受任意类型的参数。

有时这会对你带来麻烦,你会对参数做一些类型判断。有许多方法可以避免这些情况。

反例:

正例:

避免类型判断(part 2)

如果需处理的数据为字符串,整型,数组等类型,无法使用多态并仍有必要对其进行类型检测时,可以考虑使用TypeScript。

反例:

正例:

避免过度优化

现代的浏览器在运行时会对代码自动进行优化。有时人为对代码进行优化可能是在浪费时间。

这里可以找到许多真正需要优化的地方

反例:

正例:

删除无效的代码

不再被调用的代码应及时删除。

反例:

正例:

对象和数据结构

使用getters和setters

JS没有接口或类型,因此实现这一模式是很困难的,因为我们并没有类似public和private的关键词。

然而,使用getters和setters获取对象的数据远比直接使用点操作符具有优势。为什么呢?

当需要对获取的对象属性执行额外操作时。

执行set时可以增加规则对要变量的合法性进行判断。

封装了内部逻辑。

在存取时可以方便的增加日志和错误处理。

继承该类时可以重载默认行为。

从服务器获取数据时可以进行懒加载。

反例:

正例:

让对象拥有私有成员

可以通过闭包完成

反例:

正例:

单一职责原则 (SRP)

如《代码整洁之道》一书中所述,“修改一个类的理由不应该超过一个”。

将多个功能塞进一个类的想法很诱人,但这将导致你的类无法达到概念上的内聚,并经常不得不进行修改。

最小化对一个类需要修改的次数是非常有必要的。如果一个类具有太多太杂的功能,当你对其中一小部分进行修改时,将很难想象到这一修够对代码库中依赖该类的其他模块会带来什么样的影响。

反例:

正例:

开/闭原则 (OCP)

“代码实体(类,模块,函数等)应该易于扩展,难于修改。”

这一原则指的是我们应允许用户方便的扩展我们代码模块的功能,而不需要打开js文件源码手动对其进行修改。

反例:

正例:

利斯科夫替代原则 (LSP)

“子类对象应该能够替换其超类对象被使用”。

也就是说,如果有一个父类和一个子类,当采用子类替换父类时不应该产生错误的结果。

反例:

正例:

接口隔离原则 (ISP)

“客户端不应该依赖它不需要的接口;一个类对另一个类的依赖应该建立在最小的接口上。”

在JS中,当一个类需要许多参数设置才能生成一个对象时,或许大多时候不需要设置这么多的参数。此时减少对配置参数数量的需求是有益的。

反例:

正例:

依赖反转原则 (DIP)

该原则有两个核心点:

1. 高层模块不应该依赖于低层模块。他们都应该依赖于抽象接口。 2. 抽象接口应该脱离具体实现,具体实现应该依赖于抽象接口。

反例:

正例:

使用ES6的classes而不是ES5的Function

典型的ES5的类(function)在继承、构造和方法定义方面可读性较差。

当需要继承时,优先选用classes。

但是,当在需要更大更复杂的对象时,最好优先选择更小的function而非classes。

反例:

正例:

使用方法链

这里我们的理解与《代码整洁之道》的建议有些不同。

有争论说方法链不够干净且违反了德米特法则,也许这是对的,但这种方法在JS及许多库(如JQuery)中显得非常实用。

因此,我认为在JS中使用方法链是非常合适的。在class的函数中返回this,能够方便的将类需要执行的多个方法链接起来。

反例:

正例:

优先使用组合模式而非继承

在著名的设计模式一书中提到,应多使用组合模式而非继承。

这么做有许多优点,在想要使用继承前,多想想能否通过组合模式满足需求吧。

那么,在什么时候继承具有更大的优势呢?这取决于你的具体需求,但大多情况下,可以遵守以下三点:

继承关系表现为"是一个"而非"有一个"(如动物->人 和 用户->用户细节)

可以复用基类的代码("Human"可以看成是"All animal"的一种)

希望当基类改变时所有派生类都受到影响(如修改"all animals"移动时的卡路里消耗量)

反例:

正例:

测试

一些好的覆盖工具.

一些好的JS测试框架

单一的测试每个概念

反例:

正例:

并发

用Promises替代回调

回调不够整洁并会造成大量的嵌套。ES6内嵌了Promises,使用它吧。

反例:

正例:

Async/Await是较Promises更好的选择

Promises是较回调而言更好的一种选择,但ES7中的async和await更胜过Promises。

在能使用ES7特性的情况下可以尽量使用他们替代Promises。

反例:

正例:

错误处理

错误抛出是个好东西!这使得你能够成功定位运行状态中的程序产生错误的位置。

别忘了捕获错误

对捕获的错误不做任何处理是没有意义的。

代码中try/catch的意味着你认为这里可能出现一些错误,你应该对这些可能的错误存在相应的处理方案。

反例:

正例:

不要忽略被拒绝的promises

理由同try/catch.

反例:

正例:

格式化

格式化是一件主观的事。如同这里的许多规则一样,这里并没有一定/立刻需要遵守的规则。可以在这里完成格式的自动化。

大小写一致

JS是弱类型语言,合理的采用大小写可以告诉你关于变量/函数等的许多消息。

这些规则是主观定义的,团队可以根据喜欢进行选择。重点在于无论选择何种风格,都需要注意保持一致性。

反例:

正例:

调用函数的函数和被调函数应放在较近的位置

当函数间存在相互调用的情况时,应将两者置于较近的位置。

理想情况下,应将调用其他函数的函数写在被调用函数的上方。

反例:

正例:

注释

只对存在一定业务逻辑复制性的代码进行注释

注释并不是必须的,好的代码是能够让人一目了然,不用过多无谓的注释。

反例:

正例:

不要在代码库中遗留被注释掉的代码

版本控制的存在是有原因的。让旧代码存在于你的history里吧。

反例:

正例:

不需要版本更新类型注释

记住,我们可以使用版本控制。废代码、被注释的代码及用注释记录代码中的版本更新说明都是没有必要的。

需要时可以使用git log获取历史版本。

反例:

正例:

避免位置标记

这些东西通常只能代码麻烦,采用适当的缩进就可以了。

反例:

正例:

避免在源文件中写入法律评论

将你的LICENSE文件置于源码目录树的根目录。

反例:

正例:

关于本文

译者:@alivebao

原文:http://mp.weixin.qq.com/s?__biz=MjM5MTA1MjAxMQ==&mid=2651225243&idx=1&sn=b1597c58afabe2c99e87609f9193e3c7&chksm=bd49a51f8a3e2c090be18d2fd4a283f7d320feb6f07ddd324ddcf6a709b9bc9e8a9a91677836&scene=21#wechat_redirect

译文:https://github.com/alivebao/clean-code-js

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 151,829评论 1 331
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 64,603评论 1 273
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 101,846评论 0 226
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 42,600评论 0 191
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 50,780评论 3 272
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 39,695评论 1 192
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 31,136评论 2 293
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 29,862评论 0 182
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 33,453评论 0 229
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 29,942评论 2 233
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 31,347评论 1 242
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 27,790评论 2 236
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 32,293评论 3 221
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 25,839评论 0 8
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 26,448评论 0 181
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 34,564评论 2 249
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 34,623评论 2 249

推荐阅读更多精彩内容

  • Android 自定义View的各种姿势1 Activity的显示之ViewRootImpl详解 Activity...
    passiontim阅读 170,472评论 25 707
  • 在日常的开发过程中,如果大家都遵循统一的代码规范,我们就可以避免许多无缘无故的Bug,提高程序的准确性、连续性、可...
    xqqlv阅读 1,123评论 0 1
  • 第5章 引用类型(返回首页) 本章内容 使用对象 创建并操作数组 理解基本的JavaScript类型 使用基本类型...
    大学一百阅读 3,132评论 0 4
  • ES6允许使用“箭头”(=>)定义函数。 上面的箭头函数等同于: 如果箭头函数不需要参数或需要多个参数,就使用一个...
    小冕阅读 189评论 0 0
  • 我因为手痛的原因,周末未能出门,窝在宿舍里看电影。 小伙伴推荐我看《原谅他77次》。 我用...
    oh尘埃阅读 382评论 0 1