首页 前端 TypeScript 正文

TypeScript 代码整洁之道


随着 TypeScript 越来越火,更多的人开始使用 TypeScript,同时原来的 JavaScript 编码风格也不能完全适用于 TypeScript 了。

本文修改了中文版本的一些内容,比如 TSLint 等等。

2019 年 1 月,TypeScirpt 官方决定全面采用 ESLint 作为代码检查的工具,并创建了一个新项目 typescript-eslint,提供了 TypeScript 文件的解析器 @typescript-eslint/parser 和相关的配置选项 @typescript-eslint/eslint-plugin 等。而之前的两个 lint 解决方案都将弃用:

  • typescript-eslint-parser 已停止维护

  • TSLint 将提供迁移工具,并在 TypeScript-eslint 的功能足够完整后停止维护 TSLint(Once we consider ESLint feature-complete w.r.t. TSLint, we will deprecate TSLint and help users migrate to ESLint1) 综上所述,目前以及将来的 TypeScript 的代码检查方案就是 typescript-eslint

TypeScript 代码整洁之道

中文 | English

将 Clean Code 的概念适用到 TypeScript,灵感来自 clean-code-javascript

简介

TypeScript 代码整洁之道  第1张

这不是一份 TypeScript 编码风格规范,而是将 Robert C. Martin 的软件工程著作《Clean Code》 适用到 TypeScript,引导读者使用 TypeScript 编写易读、复用和可扩展的软件。

实际上,并不是每一个原则都要严格遵守,能被广泛认同的原则就更少了。这看起来虽然只是一份指导原则,但却是 Clean Code 作者对多年编程经验的凝练。

软件工程技术已有50多年的历史了,我们仍然要学习很多的东西。当软件架构和架构本身一样古老的时候,也许我们需要遵守更严格的规则。但是现在,让这些指导原则作为评估您和您的团队代码质量的试金石。

另外,理解这些原则不会立即让您变的优秀,也不意味着不会犯错。每一段代码都是从不完美开始的,通过反复走查不断趋于完美,就像黏土制作成陶艺一样,享受这个过程吧!

变量

计算机科学只存在两个难题:缓存失效和命名。—— Phil KarIton

使用有意义的变量名

做有意义的区分,让读者更容易理解变量的含义。

?反例:

function between<T>(a1: T, a2: T, a3: T) {
  return a2 <= a1 && a1 <= a3;
}


?正例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}


可读的变量名

如果你不能正确读出它,那么你在讨论它时听起来就会像个白痴。

?反例:

class DtaRcrd102 {
  private genymdhms: Date; // 你能读出这个变量名么? 
  private modymdhms: Date;
  private pszqint = '102';
}


?正例:

classCustomer {
  private generationTimestamp: Date;
  private modificationTimestamp: Date;
  private recordId = '102';
}


合并功能一致的变量

?反例:

function getUserInfo(): User;
function getUserDetails(): User;
function getUserData(): User;


?正例:

function getUser(): User;


便于搜索的名字

往往我们读代码要比写的多,所以易读性和可搜索非常重要。如果不抽取并命名有意义的变量名,那就坑了读代码的人。代码一定要便于搜索,TSLint 就可以帮助识别未命名的常量。

?反例:

//86400000 代表什么?
setTimeout(restart, 86400000);


?正例:

// 声明为常量,要大写且有明确含义。
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;
setTimeout(restart, MILLISECONDS_IN_A_DAY);


使用自解释的变量名

?反例:

declare const users:Map<string, User>;
for (const keyValue of users) {
  // ...
}


?正例:

declare const users:Map<string, User>;
for (const [id, user] of users) {
  // ...
}


避免思维映射

不要让人去猜测或想象变量的含义,明确是王道。

?反例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}0


?正例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}1


不添加无用的上下文

如果类名或对象名已经表达了某些信息,在内部变量名中不要再重复表达。

?反例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}2


?正例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}3


使用默认参数,而非短路或条件判断

通常,默认参数比短路更整洁。

?反例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}4


?正例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}5


函数

参数越少越好 (理想情况不超过2个)

限制参数个数,这样函数测试会更容易。超过三个参数会导致测试复杂度激增,需要测试众多不同参数的组合场景。 理想情况,只有一两个参数。如果有两个以上的参数,那么您的函数可能就太过复杂了。

如果需要很多参数,请您考虑使用对象。为了使函数的属性更清晰,可以使用解构,它有以下优点:

  1. 当有人查看函数签名时,会立即清楚使用了哪些属性。

  2. 解构对传递给函数的参数对象做深拷贝,这可预防副作用。(注意:不会克隆从参数对象中解构的对象和数组)

  3. TypeScript 会对未使用的属性显示警告。

?反例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}6


?正例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}7


通过 TypeScript 的类型别名,可以进一步提高可读性。

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}8


只做一件事

这是目前软件工程中最重要的规则。如果函数做不止一件事,它就更难组合、测试以及理解。反之,函数只有一个行为,它就更易于重构、代码就更清晰。如果能做好这一点,你一定很优秀!

?反例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}9


?正例:

class DtaRcrd102 {
  private genymdhms: Date; // 你能读出这个变量名么? 
  private modymdhms: Date;
  private pszqint = '102';
}0


名副其实

通过函数名就可以看得出函数实现的功能。

?反例:

class DtaRcrd102 {
  private genymdhms: Date; // 你能读出这个变量名么? 
  private modymdhms: Date;
  private pszqint = '102';
}1


?正例:

class DtaRcrd102 {
  private genymdhms: Date; // 你能读出这个变量名么? 
  private modymdhms: Date;
  private pszqint = '102';
}2


每个函数只包含同一个层级的抽象

当有多个抽象级别时,函数应该是做太多事了。拆分函数以便可复用,也让测试更容易。

?反例:

class DtaRcrd102 {
  private genymdhms: Date; // 你能读出这个变量名么? 
  private modymdhms: Date;
  private pszqint = '102';
}3


?正例:

class DtaRcrd102 {
  private genymdhms: Date; // 你能读出这个变量名么? 
  private modymdhms: Date;
  private pszqint = '102';
}4


删除重复代码

重复乃万恶之源!重复意味着如果要修改某个逻辑,需要修改多处代码?。 想象一下,如果你经营一家餐厅,要记录你的库存:所有的西红柿、洋葱、大蒜、香料等等。如果要维护多个库存列表,那是多么痛苦的事!

存在重复代码,是因为有两个或两个以上很近似的功能,只有一点不同,但是这点不同迫使你用多个独立的函数来做很多几乎相同的事情。删除重复代码,则意味着创建一个抽象,该抽象仅用一个函数/模块/类就可以处理这组不同的东西。

合理的抽象至关重要,这就是为什么您应该遵循SOLID原则。糟糕的抽象可能还不如重复代码,所以要小心!话虽如此,还是要做好抽象!尽量不要重复。

?反例:

class DtaRcrd102 {
  private genymdhms: Date; // 你能读出这个变量名么? 
  private modymdhms: Date;
  private pszqint = '102';
}5


?正例:

class DtaRcrd102 {
  private genymdhms: Date; // 你能读出这个变量名么? 
  private modymdhms: Date;
  private pszqint = '102';
}6


有时,在重复代码和引入不必要的抽象而增加的复杂性之间,需要做权衡。当来自不同领域的两个不同模块,它们的实现看起来相似,复制也是可以接受的,并且比抽取公共代码要好一点。因为抽取公共代码会导致两个模块产生间接的依赖关系。

使用Object.assign解构来设置默认对象

?反例:

class DtaRcrd102 {
  private genymdhms: Date; // 你能读出这个变量名么? 
  private modymdhms: Date;
  private pszqint = '102';
}7


?正例:

class DtaRcrd102 {
  private genymdhms: Date; // 你能读出这个变量名么? 
  private modymdhms: Date;
  private pszqint = '102';
}8


或者,您可以使用默认值的解构:

class DtaRcrd102 {
  private genymdhms: Date; // 你能读出这个变量名么? 
  private modymdhms: Date;
  private pszqint = '102';
}9


为了避免副作用,不允许显式传递undefinednull值。参见 TypeScript 编译器的--strictnullcheck选项。

不要使用Flag参数

Flag参数告诉用户这个函数做了不止一件事。如果函数使用布尔值实现不同的代码逻辑路径,则考虑将其拆分。

?反例:

classCustomer {
  private generationTimestamp: Date;
  private modificationTimestamp: Date;
  private recordId = '102';
}0


?正例:

classCustomer {
  private generationTimestamp: Date;
  private modificationTimestamp: Date;
  private recordId = '102';
}1


避免副作用 (part1)

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

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

重点是要规避常见陷阱,比如,在无结构对象之间共享状态、使用可变数据类型,以及不确定副作用发生的位置。如果你能做到这点,你才可能笑到最后!

?反例:

classCustomer {
  private generationTimestamp: Date;
  private modificationTimestamp: Date;
  private recordId = '102';
}2


?正例:

classCustomer {
  private generationTimestamp: Date;
  private modificationTimestamp: Date;
  private recordId = '102';
}3


避免副作用 (part2)

在 JavaScript 中,原类型是值传递,对象、数组是引用传递。

有这样一种情况,如果您的函数修改了购物车数组,用来添加购买的商品,那么其他使用该cart数组的函数都将受此添加操作的影响。想象一个糟糕的情况:

用户点击“购买”按钮,该按钮调用purchase函数,函数请求网络并将cart数组发送到服务器。由于网络连接不好,购买功能必须不断重试请求。恰巧在网络请求开始前,用户不小心点击了某个不想要的项目上的“Add to Cart”按钮,该怎么办?而此时网络请求开始,那么purchase函数将发送意外添加的项,因为它引用了一个购物车数组,addItemToCart函数修改了该数组,添加了不需要的项。

一个很好的解决方案是addItemToCart总是克隆cart,编辑它,并返回克隆。这确保引用购物车的其他函数不会受到任何更改的影响。

注意两点:

  1. 在某些情况下,可能确实想要修改输入对象,这种情况非常少见。且大多数可以重构,确保没副作用!(见纯函数)

  2. 性能方面,克隆大对象代价确实比较大。还好有一些很好的库,它提供了一些高效快速的方法,且不像手动克隆对象和数组那样占用大量内存。

?反例:

classCustomer {
  private generationTimestamp: Date;
  private modificationTimestamp: Date;
  private recordId = '102';
}4


?正例:

classCustomer {
  private generationTimestamp: Date;
  private modificationTimestamp: Date;
  private recordId = '102';
}5


不要写全局函数

在 JavaScript 中污染全局的做法非常糟糕,这可能导致和其他库冲突,而调用你的 API 的用户在实际环境中得到一个 exception 前对这一情况是一无所知的。

考虑这样一个例子:如果想要扩展 JavaScript 的 Array,使其拥有一个可以显示两个数组之间差异的 diff方法,该怎么做呢?可以将新函数写入Array.prototype ,但它可能与另一个尝试做同样事情的库冲突。如果另一个库只是使用diff来查找数组的第一个元素和最后一个元素之间的区别呢?

更好的做法是扩展Array,实现对应的函数功能。

?反例:

classCustomer {
  private generationTimestamp: Date;
  private modificationTimestamp: Date;
  private recordId = '102';
}6


?正例:

classCustomer {
  private generationTimestamp: Date;
  private modificationTimestamp: Date;
  private recordId = '102';
}7


函数式编程优于命令式编程

尽量使用函数式编程!

?反例:

classCustomer {
  private generationTimestamp: Date;
  private modificationTimestamp: Date;
  private recordId = '102';
}8


?正例:

classCustomer {
  private generationTimestamp: Date;
  private modificationTimestamp: Date;
  private recordId = '102';
}9


封装判断条件

?反例:

function getUserInfo(): User;
function getUserDetails(): User;
function getUserData(): User;0


?正例:

function getUserInfo(): User;
function getUserDetails(): User;
function getUserData(): User;1


避免“否定”的判断

?反例:

function getUserInfo(): User;
function getUserDetails(): User;
function getUserData(): User;2


?正例:

function getUserInfo(): User;
function getUserDetails(): User;
function getUserData(): User;3


避免判断条件

这看起来似乎不太可能完成啊。大多数人听到后第一反应是,“没有if语句怎么实现功能呢?” 在多数情况下,可以使用多态性来实现相同的功能。接下来的问题是 “为什么要这么做?” 原因就是之前提到的:函数只做一件事。

?反例:

function getUserInfo(): User;
function getUserDetails(): User;
function getUserData(): User;4


?正例:

function getUserInfo(): User;
function getUserDetails(): User;
function getUserData(): User;5


避免类型检查

TypeScript 是 JavaScript 的一个严格的语法超集,具有静态类型检查的特性。所以指定变量、参数和返回值的类型,以充分利用此特性,能让重构更容易。

?反例:

function getUserInfo(): User;
function getUserDetails(): User;
function getUserData(): User;6


?正例:

function getUserInfo(): User;
function getUserDetails(): User;
function getUserData(): User;7


不要过度优化

现代浏览器在运行时进行大量的底层优化。很多时候,你做优化只是在浪费时间。有些优秀资源可以帮助定位哪里需要优化,找到并修复它。

?反例:

function getUserInfo(): User;
function getUserDetails(): User;
function getUserData(): User;8


?正例:

function getUserInfo(): User;
function getUserDetails(): User;
function getUserData(): User;9


删除无用代码

无用代码和重复代码一样无需保留。如果没有地方调用它,请删除!如果仍然需要它,可以查看版本历史。

?反例:

function getUser(): User;0


?正例:

function getUser(): User;1


使用迭代器和生成器

像使用流一样处理数据集合时,请使用生成器和迭代器。

理由如下:

  • 将调用者与生成器实现解耦,在某种意义上,调用者决定要访问多少项。

  • 延迟执行,按需使用。

  • 内置支持使用for-of语法进行迭代

  • 允许实现优化的迭代器模式

?反例:

function getUser(): User;2


?正例:

function getUser(): User;3


有些库通过链接“map”、“slice”、“forEach”等方法,达到与原生数组类似的方式处理迭代。参见 itiriri 里面有一些使用迭代器的高级操作示例(或异步迭代的操作 itiriri-async)。

function getUser(): User;4


对象和数据结构

使用getterssetters

TypeScript 支持 getter/setter 语法。使用 getter 和 setter 从对象中访问数据比简单地在对象上查找属性要好。原因如下:

  • 当需要在获取对象属性之前做一些事情时,不必在代码中查找并修改每个访问器。

  • 执行set时添加验证更简单。

  • 封装内部表示。

  • 更容易添加日志和错误处理。

  • 可以延迟加载对象的属性,比如从服务器获取它。

?反例:

function getUser(): User;5


?正例:

function getUser(): User;6


让对象拥有 private/protected 成员

TypeScript 类成员支持 public(默认)protected 以及 private的访问限制。

?反例:

function getUser(): User;7


?正例:

function getUser(): User;8


不变性

TypeScript 类型系统允许将接口、类上的单个属性设置为只读,能以函数的方式运行。

还有个高级场景,可以使用内置类型Readonly,它接受类型 T 并使用映射类型将其所有属性标记为只读。

?反例:

function getUser(): User;9


?正例:

//86400000 代表什么?
setTimeout(restart, 86400000);0


类型 vs 接口

当可能需要联合或交集时,请使用类型。如果需要扩展实现,请使用接口。然而,没有严格的规则,只有适合的规则。

详细解释参考关于 Typescript 中typeinterface区别的解答

?反例:

//86400000 代表什么?
setTimeout(restart, 86400000);1


?正例:

//86400000 代表什么?
setTimeout(restart, 86400000);2


小、小、小!要事情说三遍

类的大小是由它的职责来度量的。按照单一职责原则,类要小。

?反例:

//86400000 代表什么?
setTimeout(restart, 86400000);3


?正例:

//86400000 代表什么?
setTimeout(restart, 86400000);4


高内聚低耦合

内聚:定义了类成员之间相互关联的程度。理想情况下,高内聚类的每个方法都应该使用类中的所有字段,实际上这不可能也不可取。但我们依然提倡高内聚。

耦合:指的是两个类之间的关联程度。如果其中一个类的更改不影响另一个类,则称为低耦合类。

好的软件设计具有高内聚性低耦合性

?反例:

//86400000 代表什么?
setTimeout(restart, 86400000);5


?正例:

//86400000 代表什么?
setTimeout(restart, 86400000);6


组合大于继承

正如“四人帮”在设计模式中所指出的那样,您尽可能使用组合而不是继承。组合和继承各有优劣。这个准则的主要观点是,如果你潜意识地倾向于继承,试着想想组合是否能更好地给你的问题建模,在某些情况下可以。

什么时候应该使用继承?这取决于你面临的问题。以下场景使用继承更好:

  1. 继承代表的是“is-a”关系,而不是“has-a”关系 (人 -> 动物 vs. 用户 -> 用户详情)。

  2. 可复用基类的代码 (人类可以像所有动物一样移动)。

  3. 希望通过更改基类对派生类进行全局更改(改变所有动物在运动时的热量消耗)。

?反例:

//86400000 代表什么?
setTimeout(restart, 86400000);7


?正例:

//86400000 代表什么?
setTimeout(restart, 86400000);8


使用方法链

非常有用的模式,在许多库中都可以看到。它让代码表达力更好,也更简洁。

?反例:

//86400000 代表什么?
setTimeout(restart, 86400000);9


?正例:

// 声明为常量,要大写且有明确含义。
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;
setTimeout(restart, MILLISECONDS_IN_A_DAY);0


SOLID原则

单一职责原则 (SRP)

正如 Clean Code 中所述,“类更改的原因不应该超过一个”。将很多功能打包在一个类看起来很诱人,就像在航班上您只能带一个手提箱。这样带来的问题是,在概念上类不具有内聚性,且有很多原因去修改类。而我们应该尽量减少修改类的次数。如果一个类功能太多,修改了其中一处很难确定对代码库中其他依赖模块的影响。

?反例:

// 声明为常量,要大写且有明确含义。
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;
setTimeout(restart, MILLISECONDS_IN_A_DAY);1


?正例:

// 声明为常量,要大写且有明确含义。
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;
setTimeout(restart, MILLISECONDS_IN_A_DAY);2


开闭原则 (OCP)

正如 Bertrand Meyer 所说,“软件实体(类、模块、函数等)应该对扩展开放,对修改封闭。” 换句话说,就是允许在不更改现有代码的情况下添加新功能。

?反例:

// 声明为常量,要大写且有明确含义。
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;
setTimeout(restart, MILLISECONDS_IN_A_DAY);3


?正例:

// 声明为常量,要大写且有明确含义。
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;
setTimeout(restart, MILLISECONDS_IN_A_DAY);4


里氏替换原则 (LSP)

对一个非常简单的概念来说,这是个可怕的术语。

它的正式定义是:“如果 S 是 T 的一个子类型,那么类型 T 的对象可以被替换为类型 S 的对象,而不会改变程序任何期望的属性(正确性、执行的任务等)“。这是一个更可怕的定义。

更好的解释是,如果您有一个父类和一个子类,那么父类和子类可以互换使用,而不会出现问题。这可能仍然令人困惑,所以让我们看一看经典的正方形矩形的例子。从数学上讲,正方形是矩形,但是如果您通过继承使用 “is-a” 关系对其建模,您很快就会遇到麻烦。

?反例:

// 声明为常量,要大写且有明确含义。
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;
setTimeout(restart, MILLISECONDS_IN_A_DAY);5


?正例:

// 声明为常量,要大写且有明确含义。
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;
setTimeout(restart, MILLISECONDS_IN_A_DAY);6


接口隔离原则 (ISP)

“客户不应该被迫依赖于他们不使用的接口。” 这一原则与单一责任原则密切相关。这意味着不应该设计一个大而全的抽象,否则会增加客户的负担,因为他们需要实现一些不需要的方法。

?反例:

// 声明为常量,要大写且有明确含义。
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;
setTimeout(restart, MILLISECONDS_IN_A_DAY);7


?正例:

// 声明为常量,要大写且有明确含义。
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;
setTimeout(restart, MILLISECONDS_IN_A_DAY);8


依赖反转原则(Dependency Inversion Principle)

这个原则有两个要点:

  1. 高层模块不应该依赖于低层模块,两者都应该依赖于抽象。

  2. 抽象不依赖实现,实现应依赖抽象。

一开始这难以理解,但是如果你使用过 Angular,你就会看到以依赖注入(DI)的方式实现了这一原则。虽然概念不同,但是 DIP 阻止高级模块了解其低级模块的细节并进行设置。它可以通过 DI 实现这一点。这样做的一个巨大好处是减少了模块之间的耦合。耦合非常糟糕,它让代码难以重构。

DIP 通常是通过使用控制反转(IoC)容器来实现的。比如:TypeScript 的 IoC 容器 InversifyJs

?反例:

// 声明为常量,要大写且有明确含义。
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;
setTimeout(restart, MILLISECONDS_IN_A_DAY);9


?正例:

declare const users:Map<string, User>;
for (const keyValue of users) {
  // ...
}0


测试

测试比发布更重要。如果没有测试或测试不充分,那么每次发布代码时都无法确保不引入问题。怎样才算是足够的测试?这取决于团队,但是拥有100%的覆盖率(所有语句和分支)会让团队更有信心。这一切都要基于好的测试框架以及覆盖率工具

没有任何理由不编写测试。有很多优秀的 JS 测试框架都支持 TypeScript,找个团队喜欢的。然后为每个新特性/模块编写测试。如果您喜欢测试驱动开发(TDD),那就太好了,重点是确保在开发任何特性或重构现有特性之前,代码覆盖率已经达到要求。

TDD(测试驱动开发)三定律

  1. 在编写不能通过的单元测试前,不可编写生产代码。

  2. 只可编写刚好无法通过的单元测试,不能编译也算不过。

  3. 只可编写刚好足以通过当前失败测试的生产代码。

F.I.R.S.T.准则

整洁的测试应遵循以下准则:

  • 快速(Fast),测试应该快(及时反馈出业务代码的问题)。

  • 独立(Independent),每个测试流程应该独立。

  • 可重复(Repeatable),测试应该在任何环境上都能重复通过。

  • 自我验证(Self-Validating),测试结果应该明确通过或者失败

  • 及时(Timely),测试代码应该在产品代码之前编写。

单一的测试每个概念

测试也应该遵循单一职责原则,每个单元测试只做一个断言。

?反例:

declare const users:Map<string, User>;
for (const keyValue of users) {
  // ...
}1


?正例:

declare const users:Map<string, User>;
for (const keyValue of users) {
  // ...
}2


测试用例名称应该显示它的意图

当测试失败时,出错的第一个迹象可能就是它的名字。

?反例:

declare const users:Map<string, User>;
for (const keyValue of users) {
  // ...
}3


?正例:

declare const users:Map<string, User>;
for (const keyValue of users) {
  // ...
}4


并发

用 Promises 替代回调

回调不够整洁而且会导致过多的嵌套(回调地狱)

有些工具使用回调的方式将现有函数转换为 promise 对象:

?反例:

declare const users:Map<string, User>;
for (const keyValue of users) {
  // ...
}5


?正例:

declare const users:Map<string, User>;
for (const keyValue of users) {
  // ...
}6


Promise 提供了一些辅助方法,能让代码更简洁:

方法 描述
Promise.resolve(value) 返回一个传入值解析后的 promise 。
Promise.reject(error) 返回一个带有拒绝原因的 promise 。
Promise.all(promises) 返回一个新的 promise,传入数组中的每个 promise 都执行完成后返回的 promise 才算完成,或第一个 promise 拒绝而拒绝。
Promise.race(promises) 返回一个新的 promise,传入数组中的某个 promise 解决或拒绝,返回的 promise 就会解决或拒绝。

Promise.all在并行运行任务时尤其有用,Promise.race让为 Promise 更容易实现超时。

Async/AwaitPromises 更好

使用async/await语法,可以编写更简洁、更易理解的链式 promise 的代码。一个函数使用async关键字作为前缀,JavaScript 运行时会暂停await关键字上的代码执行(当使用 promise 时)。

?反例:

declare const users:Map<string, User>;
for (const keyValue of users) {
  // ...
}7


?正例:

declare const users:Map<string, User>;
for (const keyValue of users) {
  // ...
}8


错误处理

抛出错误是件好事!它表示着运行时已经成功识别出程序中的错误,通过停止当前堆栈上的函数执行,终止进程(在Node.js),以及在控制台中打印堆栈信息来让你知晓。

抛出Error或 使用reject

JavaScript 和 TypeScript 允许你 throw 任何对象。Promise 也可以用任何理由对象拒绝。

建议使用 Error 类型的 throw 语法。因为你的错误可能在写有 catch语法的高级代码中被捕获。在那里捕获字符串消息显得非常混乱,并且会使调试更加痛苦。出于同样的原因,也应该在拒绝 promise 时使用 Error类型。

?反例:

declare const users:Map<string, User>;
for (const keyValue of users) {
  // ...
}9


?正例:

declare const users:Map<string, User>;
for (const [id, user] of users) {
  // ...
}0


使用 Error 类型的好处是 try/catch/finally 语法支持它,并且隐式地所有错误都具有  stack 属性,该属性对于调试非常有用。

另外,即使不用 throw 语法而是返回自定义错误对象,TypeScript在这块更容易。考虑下面的例子:

declare const users:Map<string, User>;
for (const [id, user] of users) {
  // ...
}1


详细解释请参考原文

别忘了捕获错误

捕获错误而不处理实际上也是没有修复错误,将错误记录到控制台(console.log)也好不到哪里去,因为它常常丢失在控制台大量的日志之中。如果将代码写在try/catch 中,说明那里可能会发生错误,因此应该考虑在错误发生时做一些处理。

?反例:

declare const users:Map<string, User>;
for (const [id, user] of users) {
  // ...
}2


?正例:

declare const users:Map<string, User>;
for (const [id, user] of users) {
  // ...
}3


不要忽略被拒绝的 promises

理由和不能在try/catch中忽略Error一样。

?反例:

declare const users:Map<string, User>;
for (const [id, user] of users) {
  // ...
}4


?正例:

declare const users:Map<string, User>;
for (const [id, user] of users) {
  // ...
}5


格式化

就像这里的许多规则一样,没有什么是硬性规定,格式化也是。重点是不要争论格式,使用自动化工具实现格式化。对于工程师来说,争论格式就是浪费时间和金钱。通用的原则是保持一致的格式规则

2019 年 1 月,TypeScirpt 官方决定全面采用 ESLint 作为代码检查的工具,并创建了一个新项目 typescript-eslint,提供了 TypeScript 文件的解析器 @typescript-eslint/parser 和相关的配置选项 @typescript-eslint/eslint-plugin 等。

参考配置 .eslintrc

declare const users:Map<string, User>;
for (const [id, user] of users) {
  // ...
}6


还可以参考TypeScript 风格指南和编码约定的源代码。

大小写一致

大写可以告诉你很多关于变量、函数等的信息。这些都是主观规则,由你的团队做选择。关键是无论怎么选,都要一致

?反例:

declare const users:Map<string, User>;
for (const [id, user] of users) {
  // ...
}7


?正例:

declare const users:Map<string, User>;
for (const [id, user] of users) {
  // ...
}8


类名、接口名、类型名和命名空间名最好使用“帕斯卡命名”。

变量、函数和类成员使用“驼峰式命名”。

调用函数的函数和被调函数应靠近放置

当函数间存在相互调用的情况时,应将两者靠近放置。最好是应将调用者写在被调者的上方。这就像读报纸一样,我们都是从上往下读,那么读代码也是。

?反例:

declare const users:Map<string, User>;
for (const [id, user] of users) {
  // ...
}9


?正例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}00


组织导入

使用整洁且易于阅读的import语句,您可以快速查看当前代码的依赖关系。导入语句应遵循以下做法:

  • Import语句应该按字母顺序排列和分组。

  • 应该删除未使用的导入语句。

  • 命名导入必须按字母顺序(例如:import {A, B, C} from 'foo';)。

  • 导入源必须在组中按字母顺序排列。 例如: import * as foo from 'a'; import * as bar from 'b';

  • 导入组用空行隔开。

  • 组内按照如下排序:

    • Polyfills (例如: import 'reflect-metadata';)

    • Node 内置模块 (例如: import fs from 'fs';)

    • 外部模块 (例如: import { query } from 'itiriri';)

    • 内部模块 (例如: import { UserService } from 'src/services/userService';)

    • 父目录中的模块 (例如: import foo from '../foo'; import qux from '../../foo/qux';)

    • 来自相同或兄弟目录的模块 (例如: import bar from './bar'; import baz from './bar/baz';)

?反例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}01


?正例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}02


使用 typescript 别名

为了创建整洁漂亮的导入语句,可以在tsconfig.json中设置编译器选项的pathsbaseUrl属性。

这样可以避免导入时使用较长的相对路径。

?反例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}03


?正例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}04


function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}05


注释

写注释意味着没有注释就无法表达清楚,而最好用代码去表达。

不要注释坏代码,重写吧!— Brian W. Kernighan and P. J. Plaugher

代码自解释而不是用注释

代码即文档。

?反例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}06


?正例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}07


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

版本控制存在的一个理由,就是让旧代码成为历史。

?反例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}08


?正例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}09


不要像写日记一样写注释

记住,使用版本控制!不需要保留无用代码、注释掉的代码,尤其像日记一样的注释。使用git log来获取历史。

?反例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}10


?正例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}11


避免使用注释标记位置

它们常常扰乱代码。要让代码结构化,函数和变量要有合适的缩进和格式。

另外,你可以使用支持代码折叠的IDE (看下 Visual Studio Code 代码折叠).

?反例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}12


?正例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}13


TODO 注释

当发现自己需要在代码中留下注释,以提醒后续改进时,使用// TODO注释。大多数IDE都对这类注释提供了特殊的支持,你可以快速浏览整个TODO列表。

VSCode 可以使用 TODO Highlight

但是,请记住TODO注释并不是坏代码的借口。

?反例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}14


?正例:

function between<T>(value: T, left: T, right: T) {
  return left <= value && value <= right;
}15
原文:https://juejin.cn/post/7096358998198190111
打赏
海报

本文转载自互联网,旨在分享有价值的内容,文章如有侵权请联系删除,部分文章如未署名作者来源请联系我们及时备注,感谢您的支持。

转载请注明本文地址:https://www.shouxicto.com/article/4051.html

相关推荐

发布评论

ainiaobaibaibaibaobaobeishangbishibizuichiguachijingchongjingdahaqiandaliandangaodw_dogedw_erhadw_miaodw_tuzidw_xiongmaodw_zhutouganbeigeiliguiguolaiguzhanghahahahashoushihaixiuhanheixianhenghorse2huaixiaohuatonghuaxinhufenjiayoujiyankeaikeliankouzhaokukuloukunkuxiaolandelinileimuliwulxhainiolxhlikelxhqiuguanzhulxhtouxiaolxhwahahalxhzanningwennonuokpinganqianqiaoqinqinquantouruoshayanshengbingshiwangshuaishuijiaosikaostar0star2star3taikaixintanshoutianpingtouxiaotuwabiweifengweiquweiwuweixiaowenhaowoshouwuxiangjixianhuaxiaoerbuyuxiaokuxiaoxinxinxinxinsuixixixuyeyinxianyinyueyouhenghengyuebingyueliangyunzanzhajizhongguozanzhoumazhuakuangzuohenghengzuoyi
支付宝
微信
赞助本站