TypeScript 代码整洁之道

Posted 2021-02-17 iebush

干净整洁的代码，不但质量更可靠，也为后期升级、维护打下了良好的基础。那么，整洁代码的衡量标准是什么？本文将 Robert C. Martin 的 Clean Code 思想融入到 TypeScript，一起探讨研究代码整洁之道。

 

WTFs/Minute

 

1. 命名的艺术

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

 

给变量命名确实是一件痛苦的事情，尤其随着项目越来越复杂，代码库越来越庞大，你才会发现命名也是一门艺术，好的命名原来是如此重要。

 

1.1 有意义的变量名

取一个有明确的具体含义的变量名。

 

反例：

 

const yyyymmdd = moment().format("YYYY/MM/DD");

正例：

 

const currentDate = moment().format("YYYY/MM/DD");

1.2 可读的变量名

如果你不能正确读出它，那么在讨论它时你就会很别扭。

 

反例：

 

class Usr123 {

  private asdf = ‘123‘;

  // ... 

}

正例：

 

class User {

  private id = ‘123‘;

  // ...

}

1.3 可搜索的名字

正常情况下，我们阅读理解代码的时间要比写代码多，所以变量的可搜索非常重要。如果不抽取并命名为变量，那就坑了读代码的人。可以使用工具 TSLint，它可以帮助识别未命名的常量。

 

反例：

 

setTimeout(restart, 86400000); //86400000 代表什么？它是魔数！

正例：

 

// 声明为常量，要大写且有明确含义。

const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;

 

setTimeout(restart, MILLISECONDS_IN_A_DAY);

1.4 使用自解释的变量名

反例：

 

declare const users: Map;

 

for (const kv of users) {

  // ...

}

正例：

 

declare const users: Map;

// 变量名解析自身的含义

for (const [id, user] of users) {

  // ...

}

1.5 合并功能一致的变量

功能重复的情况下，要精简成一个，其余都是冗余代码。

 

反例：

 

function getUserInfo(): User;

function getUserDetails(): User;

function getUserData(): User;

正例：

 

function getUser(): User;

1.6 避免思维映射

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

 

反例：

 

const u = getUser();

const s = getSubscription();

const t = charge(u, s);

正例：

 

const user = getUser();

const subscription = getSubscription();

const transaction = charge(user, subscription);

1.7 不加无用的上下文

如果类型名已经表达了明确的信息，那么，内部变量名中不要再重复表达。

 

反例：

 

type User = {

  userId: string;

  userName: string;

  userAge: number;

}

正例：

 

type User = {

  id: string;

  name: string;

  age: string;

}

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

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

 

反例：

 

function loadPages(count: number) {

  const loadCount = count !== undefined ? count : 10;

  // ...

}

正例：

 

function loadPages(count: number = 10) {

  // ...

}

对于我们国内程序员来说，取个有意义的变量名也着实考验英语基本功。可以尝试使用 CODELF 变量命名神器，在 VSCode、Sublime Text 都有插件。另外，对现有代码的命名进行重构，最好使用 IDE 自带的重构功能，避免出错。

 

CODELF

 

2. 函数

2.1 参数越少越好（理想情况不超过 2 个）

函数参数要少，这样对函数的测试会更简单。如果参数超过 3 个，那么测试复杂度会激增，因为需要测试不同参数之间的组合场景。UT 的覆盖率也很难保证。

 

通常，只有一两个参数。若有两个以上的参数，就要认真考虑函数的功能是否可以拆分。

 

但在有些情况下，确实需要很多参数，可以考虑使用对象。但若要函数的定义更清晰，最好使用解构，它有以下优点：

 

查看函数签名，即会清楚使用了哪些属性。

解构对传递给函数的参数对象做深拷贝，可以预防副作用。（注意：不会克隆从参数对象中解构的对象和数组）

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

反例：

 

function reqeust(method: string, url: string, body: string, headers: string) {

  // ...

}

 

reqeust(‘POST‘, ‘/api/service/v1/users‘, body, headers);

正例：

 

function reqeust(method: string, url: string, body: string, headers: string) {

  // ...

}

 

reqeust(

  {

    method: ‘POST‘,

    url: ‘/api/service/v1/users‘,

    body: body,

    headers: headers

  }

);

也可以使用 TypeScript 的类型别名，进一步提高可读性。

 

type RequestOptions = {method: string, url: string, body: string, headers: string};

 

function request(options: RequestOptions) {

  // ...

}

 

reqeust(

  {

    method: ‘POST‘,

    url: ‘/api/service/v1/users‘,

    body: body,

    headers: headers

  }

);

2.2 只做一件事

这是目前最重要的一条规则。如果函数做的不止一件事，那么，它将很难理解、使用以及测试。反之，单一功能的函数，会让代码更清晰。一定要做好这一点！