Typescript 代码整洁之道

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

介绍

Humorous image of software quality estimation as a count of how many expletives
you shout when reading code

软件工程原理，源自 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) {
  // ...
}
复制代码

⬆ 返回顶部