Typescript 代码整洁之道

适用于 Typescript 的代码整洁之道。 受到 clean-code-javascript 的启发。

目录

1. 介绍
2. 变量
3. 函数
4. Objects and Data Structures
5. Classes
6. SOLID
7. Testing
8. Concurrency
9. Error Handling
10. Formatting
11. Comments
12. Translations

介绍

软件工程原理，源自 Robert C. Martin's 的书 Clean Code, 适用于 TypeScript。 这不是风格指南，它是在 TypeScript 中生成 可读，可重用和可重构 软件的指南。

并不是每一个原则都必须严格遵照，广泛认同的甚至更少。这些只是准则，仅此而已，但他们倒是 Clean Code 一书的做者根据自身多年的编程体会而提炼撰写出来的。

咱们的软件工程技术只有50多年的历史，咱们还有不少东西须要学习。当软件架构与架构自己同样古老时，也许那时咱们会有更难遵循的规则。如今，让这些指导方针做为一个试金石，用来评估您和您的团队所生成的 Typescript 代码的质量.

除此以外：知道这些并不会当即使你成为一个更好的软件开发者，这些规则伴随你工做多年后并不意味着你就不会犯错误了。每一段代码都是做为初稿开始的，就像湿粘土被塑形成最终形状同样。最终，当咱们与小伙伴们一块儿审查时，咱们会凿掉不完美之处。不要由于这些须要改进的初稿而阻碍本身技术的提高。先干掉代码吧！

⬆ 返回顶部

变量

使用有意义的变量名

以这样的方式区分名称，以便读者知道他们的差别究竟是什么。

反例:

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

复制代码

正例:

function between<T>(value: T, left: T, right: T): boolean {
  return left <= value && value <= right;
}
复制代码

⬆ 返回顶部

使用可拼读的变量名

若是你不能拼读他，你只能像个白痴同样去声明它。

反例:

type DtaRcrd102 = {
  genymdhms: Date;
  modymdhms: Date;
  pszqint: number;
}
复制代码

正例:

type Customer = {
  generationTimestamp: Date;
  modificationTimestamp: Date;
  recordId: number;
}
复制代码

⬆ 返回顶部

对于相同类型的变量只使用同一个单词

反例:

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) {
  // 迭代用户地图
}
复制代码

⬆ 返回顶部

避免心领神会

显式优于隐式。
清晰是王道。

反例:

const u = getUser();
const s = getSubscription();
const t = charge(u, s);
复制代码

正例:

const user = getUser();
const subscription = getSubscription();
const transaction = charge(user, subscription);
复制代码

⬆ 返回顶部

不要添加不须要的上下文

若是你的 类/类型/对象 名称中已经有说明，不要在你的变量中重复它们。

反例:

type Car = {
  carMake: string;
  carModel: string;
  carColor: string;
}

function print(car: Car): void {
  console.log(`${car.carMake} ${car.carModel} (${car.carColor})`);
}
复制代码

正例:

type Car = {
  make: string;
  model: string;
  color: string;
}

function print(car: Car): void {
  console.log(`${car.make} ${car.model} (${car.color})`);
}
复制代码

⬆ 返回顶部

使用默认参数而不是短路表达式或条件语句

默认参数一般比短路表达式更清晰。

反例:

function loadPages(count?: number) {
  const loadCount = count !== undefined ? count : 10;
  // ...
}
复制代码

正例:

function loadPages(count: number = 10) {
  // ...
}
复制代码

⬆ 返回顶部