TypeScript 代码整洁之道- 注释

将CleanCode的概念适用到TypeScript，灵感来自clean-code-javascript。
原文地址: clean-code-typescript
中文地址: clean-code-typescript

简介

image

这不是一份TypeScript设计规范，而是将RobertC.Martin的软件工程著作《CleanCode》适用到TypeScript，指导读者使用TypeScript编写易读、可复用和易重构的软件。

注释

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

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

代码自解释而不是用注释

代码即文档。

反例:

// Check if subscription is active.

if (subscription.endDate > Date.now) {  }

正例:

const isSubscriptionActive = subscription.endDate > Date.now;

if (isSubscriptionActive) { /* ... */ }

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

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

反例:

class User {

  name: string;

  email: string;

  // age: number;

  // jobPosition: string;

}

正例:

class User {

  name: string;

  email: string;

}

不要像写日记一样写注释

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

反例:

/**

 * 2016-12-20: Removed monads, didn't understand them (RM)

 * 2016-10-01: Improved using special monads (JP)

 * 2016-02-03: Added type-checking (LI)

 * 2015-03-14: Implemented combine (JR)

 */

function combine(a:number, b:number): number {

  return a + b;

}

正例:

function combine(a:number, b:number): number {

  return a + b;

}

避免使用注释标记位置

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

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

反例:

////////////////////////////////////////////////////////////////////////////////

// Client class

////////////////////////////////////////////////////////////////////////////////

class Client {

  id: number;

  name: string;

  address: Address;

  contact: Contact;

  ////////////////////////////////////////////////////////////////////////////////

  // public methods

  ////////////////////////////////////////////////////////////////////////////////

  public describe(): string {

    // ...

  }

  ////////////////////////////////////////////////////////////////////////////////

  // private methods

  ////////////////////////////////////////////////////////////////////////////////

  private describeAddress(): string {

    // ...

  }

  private describeContact(): string {

    // ...

  }

};

正例:

class Client {

  id: number;

  name: string;

  address: Address;

  contact: Contact;

  public describe(): string {

    // ...

  }

  private describeAddress(): string {

    // ...

  }

  private describeContact(): string {

    // ...

  }

};

TODO 注释

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

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

反例:

function getActiveSubscriptions(): Promise<Subscription[]> {
  // ensure `dueDate` is indexed.
  return db.subscriptions.find({ dueDate: { $lte: new Date() } });
}

正例:

function getActiveSubscriptions(): Promise<Subscription[]> {
  // TODO: ensure `dueDate` is indexed.
  return db.subscriptions.find({ dueDate: { $lte: new Date() } });
}

上一章：TypeScript 代码整洁之道- 格式化