17. 注釋

17.1?使用?/** ... */?作為多行注釋。包含描述、指定所有參數(shù)和返回值的類(lèi)型和值。

// bad
// make() returns a new element
// based on the passed in tag name
//
// @param {String} tag
// @return {Element} element
function make(tag) {

  // ...stuff...

  return element;
}

// good
/**
 * make() returns a new element
 * based on the passed in tag name
 *
 * @param {String} tag
 * @return {Element} element
 */
function make(tag) {

  // ...stuff...

  return element;
}

17.2?使用?//?作為單行注釋。在評(píng)論對(duì)象上面另起一行使用單行注釋。在注釋前插入空行。

// bad
const active = true;  // is current tab

// good
// is current tab
const active = true;

// bad
function getType() {
  console.log('fetching type...');
  // set the default type to 'no type'
  const type = this._type || 'no type';

  return type;
}

// good
function getType() {
  console.log('fetching type...');

  // set the default type to 'no type'
  const type = this._type || 'no type';

  return type;
}

17.3?給注釋增加?FIXME?或?TODO?的前綴可以幫助其他開(kāi)發(fā)者快速了解這是一個(gè)需要復(fù)查的問(wèn)題，或是給需要實(shí)現(xiàn)的功能提供一個(gè)解決方式。這將有別于常見(jiàn)的注釋?zhuān)驗(yàn)樗鼈兪强刹僮鞯?。使?code>FIXME -- need to figure this out?或者?TODO -- need to implement。

17.4?使用?// FIXME: 標(biāo)注問(wèn)題。

class Calculator {
  constructor() {
    // FIXME: shouldn't use a global here
    total = 0;
  }
}

17.5?使用?// TODO: 標(biāo)注問(wèn)題的解決方式。

class Calculator {
  constructor() {
    // TODO: total should be configurable by an options param
    this.total = 0;
  }
}