clean-code-typescript

2019-02-12 admin

原文链接 适用于TypeScript的Clean Code(简洁代码)概念 启发来自于clean-code-javascript

介绍

68747470733a2f2f7777772e6f736e6577732e636f6d2f696d616765732f636f6d6963732f7774666d2e6a7067 软件工程原理,来自于Robert C.Martin’s的《Clean Code》一书,适用于Typescript.clean-code-typescript不是一个风格指南,它是一个在TypeScript中生成可读的、可重用的和可重构的软件的指南。

并非每个原则都需要我们严格的遵循,原则越少越容易得到大家的认同。这里仅仅有一些准则,但这些准则是Clean Code作者多年经验的总结。

我们的软件工程仅仅只有50多年的历史,并且我们还在不断的学习。当软件架构与架构一样古老时,说不定我们还会有更难遵循的规则。但是现在,现在,让这些指南作为评估您和您的团队生成的TypeScript代码质量的试金石。

还有一件事:了解这些规范并不会让你立即就成为一位更好的开发人员,按照这个规范工作也并不会意味着你再未来多年内,不会犯错。每一段代码一开始都是一个初稿,就像黏土被塑造成最终形状前一样。最后,我们和我们的同行一起审查,然后凿掉不完美的地方。不要因为需要改进初稿而退缩,一起打败代码吧!

变量

使用具有意义的变量名称

已这种方式提供名称,能够让读者很轻松的知道这个变量提供了什么。 Bad

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

Good

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

使用可读的变量名称

如果这个变量名称不能发音,你将会像个白痴一样和别人讨论这个变量。 Bad

type DtaRcrd102 = {
    genymdhms: Data;
    modymdhms: Data;
    pszqint: number;
}

Good

type Customer = {
    generationTimestamp: Date;
    modificationTimestamp: Date;
    recordId: number;
}

对用相同类型的变量使用相同的词汇

Bad

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

Good

function getUser(): User;

使用可搜索的名称

我们会阅读比我们写的代码更多的代码。我们编写的代码是可读的、可搜索的,这一点很重要。对有意义的变量不进行命名最终将会导致我们的程序更难理解。确保你的变量名称是可搜索的。像TSLint这样的工具可以帮助识别未命名的常量。 Bad

// What the heck is 86400000 for?
setTimeout(restart, 86400000);

Good

// Declare them as capitalized named constants.
const MILLISECONDS_IN_A_DAY = 24 * 60 * 60 * 1000;

setTimeout(restart, MILLISECONDS_IN_A_DAY);

使用带有解释性的变量

Bad

declare const users: Map<string, User>;

for (const keyValue of users) {
  // iterate through users map
}

Good

declare const users: Map<string, User>;

for (const [id, user] of users) {
  // iterate through users map
}

避免心理映射

显式永远优于隐式。清晰表达才是王道! Bad

const u = getUser();
const s = getSubscription();
const t = charge(u, s);

Good

const user = getUser();
const subscription = getSubscription();
const transaction = charge(user, subscription);

不要添加不需要的上下文

如果你的类/类型/对象的名称已经告诉了你一些信息,不要在变量中再重复这些信息。 Bad

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

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

Good

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

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

使用默认参数而不是判断条件

默认参数通常比短路更清晰。 Bad

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

Good

function loadPages(count: number = 10) {
  // ...
}

函数

函数参数(2个或者更少)

限制函数的参数数量这一点非常的重要,更少的参数意味着更加容易测试。超过3个的参数会使你必须为多种可能编写多个单独的变量来进行测试,这是一件非常痛苦的事情。 只有一个或两个参数是一个理想情况,如果可能的话,我们尽量避免3个参数。应该整合除此之外的任何东西。通常,如果你的函数有两个以上的参数,那么你的函数可能试图做过多的事情了。如果不是,大多数情况下,你可以通过更高级别的对象来作为参数。 如果你发现你需要大象的参数,请尝试使用对象。 为了明确函数所期望的属性,你能够使用destructuring语句。这有游一些优点:

  1. 当有人查看函数签名的时候,他会立刻知道正在使用的属性
  2. destructuring还会克隆传递给函数的参数对象的指定原始值。这有助于防止副作用。注意:解构对象中的object和array不会被克隆
  3. TypeScript会警告您未使用的属性,如果没有destructuring,这将是不可能的。

Bad

function createMenu(title: string, body: string, buttonText: string, cancellable: boolean) {
  // ...
}

createMenu('Foo', 'Bar', 'Baz', true);

Good

function createMenu(options: { title: string, body: string, buttonText: string, cancellable: boolean }) {
  // ...
}

createMenu({
  title: 'Foo',
  body: 'Bar',
  buttonText: 'Baz',
  cancellable: true
});

你可以通过type aliases来进一步的提高可读性

type MenuOptions = { title: string, body: string, buttonText: string, cancellable: boolean };

function createMenu(options: MenuOptions) {
  // ...
}

createMenu({
  title: 'Foo',
  body: 'Bar',
  buttonText: 'Baz',
  cancellable: true
});

函数应该只做一件事

这是迄今为止软件工程中最重要的规则。当一个函数做更多的事情时,他们更难编写,测试和推理。当你的函数只执行一个操作时,你的函数将更容易重构,并且你的代码也更加清晰。 Bad

function emailClients(clients: Client) {
  clients.forEach((client) => {
    const clientRecord = database.lookup(client);
    if (clientRecord.isActive()) {
      email(client);
    }
  });
}

Good

function emailClients(clients: Client) {
  clients.filter(isActiveClient).forEach(email);
}

function isActiveClient(client: Client) {
  const clientRecord = database.lookup(client);
  return clientRecord.isActive();
}

函数名称应该说明它们的作用

Bad

function addToDate(date: Date, month: number): Date {
  // ...
}

const date = new Date();

// It's hard to tell from the function name what is added
addToDate(date, 1);

Good

function addMonthToDate(date: Date, month: number): Date {
  // ...
}

const date = new Date();
addMonthToDate(date, 1);

函数应该只是一个抽象级别

当你有多个抽象级别时,你的函数通常做得太多了.拆分功能可以实现可重用性和更轻松的测试。 Bad

function parseCode(code: string) {
  const REGEXES = [ /* ... */ ];
  const statements = code.split(' ');
  const tokens = [];

  REGEXES.forEach((regex) => {
    statements.forEach((statement) => {
      // ...
    });
  });

  const ast = [];
  tokens.forEach((token) => {
    // lex...
  });

  ast.forEach((node) => {
    // parse...
  });
}

Good

const REGEXES = [ /* ... */ ];

function parseCode(code: string) {
  const tokens = tokenize(code);
  const syntaxTree = parse(tokens);

  syntaxTree.forEach((node) => {
    // parse...
  });
}

function tokenize(code: string): Token[] {
  const statements = code.split(' ');
  const tokens: Token[] = [];

  REGEXES.forEach((regex) => {
    statements.forEach((statement) => {
      tokens.push( /* ... */ );
    });
  });

  return tokens;
}

function parse(tokens: Token[]): SyntaxTree {
  const syntaxTree: SyntaxTree[] = [];
  tokens.forEach((token) => {
    syntaxTree.push( /* ... */ );
  });

  return syntaxTree;
}

删除重复的代码

尽量避免重复代码。重复代码是一件非常糟糕的事情,因为它以为着如果你需要更改某个逻辑的时候,你需要在多个位置来更改内容。 通常你会有重复的代码,因为你有两个或两个以上略有不同的东西,它们有很多共同之处,但是它们之间的差异迫使你有两个或多个独立的函数来执行大部分相同的事情。删除重复代码意味着创建一个抽象,只需一个函数/模块/类就可以处理这组不同的东西。 获得正确的抽象是至关重要的,这就是为什么你应该遵循SOLID原则.糟糕的抽象比重复代码更加糟糕,所以请更加小心。说完这个,如果你能做出很好的抽象,那就做吧!不要重复自己,否则你会发现自己在想要改变一件事的时候更新多个地方。 Bad

function showDeveloperList(developers: Developer[]) {
  developers.forEach((developer) => {
    const expectedSalary = developer.calculateExpectedSalary();
    const experience = developer.getExperience();
    const githubLink = developer.getGithubLink();

    const data = {
      expectedSalary,
      experience,
      githubLink
    };

    render(data);
  });
}

function showManagerList(managers: Manager[]) {
  managers.forEach((manager) => {
    const expectedSalary = manager.calculateExpectedSalary();
    const experience = manager.getExperience();
    const portfolio = manager.getMBAProjects();

    const data = {
      expectedSalary,
      experience,
      portfolio
    };

    render(data);
  });
}

Good

class Developer {
  // ...
  getExtraDetails() {
    return {
      githubLink: this.githubLink,
    }
  }
}

class Manager {
  // ...
  getExtraDetails() {
    return {
      portfolio: this.portfolio,
    }
  }
}

function showEmployeeList(employee: Developer | Manager) {
  employee.forEach((employee) => {
    const expectedSalary = employee.calculateExpectedSalary();
    const experience = employee.getExperience();
    const extra = employee.getExtraDetails();

    const data = {
      expectedSalary,
      experience,
      extra,
    };

    render(data);
  });
}

你应该对重复代码持批评态度。有时候,你需要在重复代码和引入不必要的抽象带来的复杂度之间权衡。当来自于不同模块的两个实现看起来很相似但又存在于不同的域当中,重复代码是可以被接受的,并且它优于提取一个公共代码。在这种情况下,提取公共代码,将会引入两个模块之间的间接依赖关系。

设置默认对象和对象属性或解构(destructuring)

Bad

type MenuConfig = {title?: string, body?: string, buttonText?: string, cancellable?: boolean};

function createMenu(config: MenuConfig) {
    config.title = config.title || 'Foo';
    config.body = config.body || 'Bar';
    config.buttonText = config.buttonText || 'Baz';
    config.cancellable = config.cancellable !== undefined ?         config.cancellable : true;

  // ...
}

createMenu({body: 'Bar'})

Good

type MenuConfig = { title?: string, body?: string, buttonText?: string, cancellable?: boolean };

function createMenu(config: MenuConfig) {
  const menuConfig = Object.assign({
    title: 'Foo',
    body: 'Bar',
    buttonText: 'Baz',
    cancellable: true
  }, config);

  // ...
}

createMenu({ body: 'Bar' });

另外,你也可以通过解构来提供默认值:

type MenuConfig = { title?: string, body?: string, buttonText?: string, cancellable?: boolean };

function createMenu({ title = 'Foo', body = 'Bar', buttonText = 'Baz', cancellable = true }: MenuConfig) {
  // ...
}

createMenu({ body: 'Bar' });

通过显式传入undefined或null值来避免任何副作用和意外行为,你可以告诉TypeScript不允许这样做。TypeScript选项–strictNullChecks

不要使用标志作为函数参数

标志会告诉你的用户这个函数不止做一件事,但函数应该只做一件事。如果你的函数按照布尔值来判断执行不同的代码,请将你的函数拆分。 Bad

function createFile(name: string, temp: boolean) {
  if (temp) {
    fs.create(`./temp/${name}`);
  } else {
    fs.create(name);
  }
}

Good

function createTempFile(name: string) {
  createFile(`./temp/${name}`);
}

function createFile(name: string) {
  fs.create(name);
}

避免副作用(1)

如果一个函数除了取参数并返回一个或多个值以外还执行其他任何操作,则这个函数产生了副作用。这个副作用可能是写一个文件,修改一些全局变量,或者将所有资金都给了一个陌生人。 现在,你确实需要副作用。就像前面的例子,你可能需要写入文件。不要有多个函数和类来写入同一个特定的文件,而是应该提供一个唯一的服务来做这个事情。 Bad

// Global variable referenced by following function.
let name = 'Robert C. Martin';

function toBase64() {
  name = btoa(name);
}

toBase64();
// If we had another function that used this name, now it'd be a Base64 value

console.log(name); // expected to print 'Robert C. Martin' but instead 'Um9iZXJ0IEMuIE1hcnRpbg=='

Good

const name = 'Robert C. Martin';

function toBase64(text: string): string {
  return btoa(text);
}

const encodedName = toBase64(name);
console.log(name);

避免副作用(2)

在JavaScript中,值、对象、数组是通过传递引用来传递的。对于对象和数组,如果你的函数直接去改变你的数组,如例子,直接添加物品到当前购物车下,其他使用这个购物车的函数的功能将会受到影响。这可能很好,但也可能很糟糕,让我们想象一个糟糕的情况: 用户点击了“购买”按钮,按钮调用了购买函数,该函数将购物车数组发送到服务器。由于网络连接不好,购买函数必须重试。现在,如果在此期间用户在网络请求开始之前意外地点击了他们实际上不想要的项目上的“添加到购物车”按钮,该怎么办?如果这发生在网络请求之前,则购买功能将会意外的添加一个项目,因为addItemToCart函数通过对购物车的引用,将不需要的项目添加进入了购物车。 一个很好的解决方案是,addItemCart始终克隆购物车,并对克隆的购物车进行修改并返回。这样可以确保其他使用购物车的函数不会受到任何更改的影响。 有两个需要注意的地方: 1.在某些情况下,你可能确实需要修改输入的对象,但如果你使用本指南进行编程时,你会发现这种情况非常少。大多数情况下都可以重构为没有副作用的函数。(参考纯函数) 2.克隆大对象对性能上的影响是非常严重的。幸运的是,这在实际开发中并不是一个大问题,因为有很好的库让这种编程方法变快,而不用手动克隆以占用大量的内存。 Bad

function addItemToCart(cart: CartItem[], item: Item): void {
  cart.push({ item, date: Date.now() });
};

Good

function addItemToCart(cart: CartItem[], item: Item): CartItem[] {
  return [...cart, { item, date: Date.now() }];
};

不要写全局函数

污染全局是一个非常糟糕的做法,因为这样做你可能会和其他库冲突,并且你的api用户在生产中获得异常之前,都不会很好的去处理。让我们考虑一个例子:如果你想扩展JavaScript的原生Array方法以获得一个可以显示两个数组之间差异的diff方法,该怎么办?你可以写一个新的函数到Array.prototype中,但是他可能会与另外一个试图做同样事情的库发生冲突。如果那个其他库只是使用diff来找到数组的第一个和最后一个元素之间的区别怎么办?这就是为什么使用类并简单地扩展Array比全局函数更好的原因。 Bad

declare global {
  interface Array<T> {
    diff(other: T[]): Array<T>;
  }
}

if (!Array.prototype.diff) {
  Array.prototype.diff = function <T>(other: T[]): T[] {
    const hash = new Set(other);
    return this.filter(elem => !hash.has(elem));
  };
}

good

class MyArray<T> extends Array<T> {
  diff(other: T[]): T[] {
    const hash = new Set(other);
    return this.filter(elem => !hash.has(elem));
  };
}

多使用函数式编程而不是命令式编程

尽可能多的使用这种编程方式 Bad

const contributions = [
  {
    name: 'Uncle Bobby',
    linesOfCode: 500
  }, {
    name: 'Suzie Q',
    linesOfCode: 1500
  }, {
    name: 'Jimmy Gosling',
    linesOfCode: 150
  }, {
    name: 'Gracie Hopper',
    linesOfCode: 1000
  }
];

let totalOutput = 0;

for (let i = 0; i < contributions.length; i++) {
  totalOutput += contributions[i].linesOfCode;
}

Good

const contributions = [
  {
    name: 'Uncle Bobby',
    linesOfCode: 500
  }, {
    name: 'Suzie Q',
    linesOfCode: 1500
  }, {
    name: 'Jimmy Gosling',
    linesOfCode: 150
  }, {
    name: 'Gracie Hopper',
    linesOfCode: 1000
  }
];

const totalOutput = contributions
  .reduce((totalLines, output) => totalLines + output.linesOfCode, 0);

封装条件语句

Bad

if (subscription.isTrial || account.balance > 0) {
  // ...
}

Good

function canActivateService(subscription: Subscription, account: Account) {
  return subscription.isTrial || account.balance > 0
}

if (canActivateService(subscription, account)) {
  // ...
}

避免负条件

Bad

function isEmailNotUsed(email: string): boolean {
  // ...
}

if (isEmailNotUsed(email)) {
  // ...
}

Good

function isEmailUsed(email): boolean {
  // ...
}

if (!isEmailUsed(node)) {
  // ...
}

[转载]原文链接:https://segmentfault.com/a/1190000018130356

本站文章除注明转载外,均为本站原创或编译。欢迎任何形式的转载,但请务必注明出处。

转载请注明:文章转载自 JavaScript中文网 [https://www.javascriptcn.com]

本文地址:https://www.javascriptcn.com/read-53605.html

文章标题:clean-code-typescript

相关文章
千呼万唤始出来!一键构建Vue-TypeScript应用
A simple TypeScript CLI for scaffolding Vue.js projects. Installation Prerequisites: Node.js (&gt;=4.x, 6.x preferred)...
2017-12-20
使用 TypeScript 构建 Koa2 项目的最佳实践
the best practice of building Koa2 with TypeScript. 中文 usage clone repo. git clone git@github.com:DhyanaChina/koa2-type...
2018-02-27
vscode-eslint的踩坑实践--typescript无法格式化
引言 最近开发的前端项目随着开发的人员越来越多,代码规范已经是一个很难避免的问题了,虽然百度有fecs这个规则检查,但是不论是icode或者是项目本地都没有配置或检查,完全靠自觉,这是件非常扯淡的事。 icode负责人表示暂时没法支持这个,...
2018-03-01
微信小程序中生成二维码工具:weapp.qrcode.js
前言 在近期的小程序开发中,有一个离线生成二维码的需求。当时想到了一些优秀的前端开源库 jquery-qrcode 和 node-qrcode,由于小程序中没有DOM的概念,这些库在小程序中并不适用。 所以,针对微信小程序的特点,封装了 w...
2018-02-03
LeetCode 算法题刷题心得(JavaScript)
花了十几天,把《算法》看了一遍然后重新 AC 了一遍 LeetCode 的题,收获颇丰。这次好好记录下心得。 我把所有做题的代码都放在 github 上以供参考。 项目地址:github.com/violetjack/… 题目地址: le...
2018-05-10
使用vscode,新建.vue文件,tab自动生成vue代码模板
第一步: 新建模板并保存 文件 --&gt; 首选项 --&gt; 用户代码片段 --&gt; 输入vue,选择vue.json --&gt;复制 第三步中的模板内容中内容保存 第二步: 添加配置,让vscode允许自定义的代码片段提示出来...
2018-04-08
使用JavaScript 插件qrcode.js生成二维码功能
效果图: qrcode.js这是一个使用比较多的js生成二维码的插件,使用也很方便,第一次用,记录一下使用方法; 首先,导入js,这个网上可以找到,附上地址:https://github.com/davidshimjs/qrcodejs/...
2017-03-16
TypeScript 2.7 记录
针对ts 2.7版本的特性作专门的实例,希望能加深理解。实例github地址 官方日志文档 增加常量声明的属性的支持(Constant-named properties) 对于常量,有更加智能的提示 const Foo = &quot;...
2018-05-18
用JavaScript实现PHP的urlencode与urldecode函数
很多朋友说JavaScript的decodeURI函数也可以实现,但有bug所有呢,下面看下下面的函数,经过测试使用暂时没什么问题,我在之前的文章说过,这个和php的urldecode函数根本不是一回事。下面是我根据高人的代码改写的Java...
2017-03-29
JavaScript通过keyCode值判断单击键盘上某个键,然后触发指定的事件方法
当单击按键时触发事件 document.onkeydown = function (e) { e = e || event; if (e.keyCode == 13) { &#x2F;&#x2F;判断是否单击的ent...
2017-03-17
回到顶部