新美集团前端文档

# 注释

  • 18.1 多行注释用 /** ... */

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

  // ...

  return element;
}

// good
/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make(tag) {

  // ...

  return element;
}

  • 18.2 单行注释用//，将单行注释放在被注释区域上面。如果注释不是在第一行，那么注释前面就空一行

    // 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;
}

// also good
function getType() {
  // set the default type to 'no type'
  const type = this._type || 'no type';

  return type;
}

  • 18.3 所有注释开头空一格，方便阅读。 eslint: spaced-comment (opens new window)

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

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

// bad
/**
 *make() returns a new element
 *based on the passed-in tag name
 */
function make(tag) {

  // ...

  return element;
}

// good
/**
 * make() returns a new element
 * based on the passed-in tag name
 */
function make(tag) {

  // ...

  return element;
}

  • 18.4 在你的注释前使用FIXME'或TODO'前缀， 这有助于其他开发人员快速理解你指出的需要重新访问的问题， 或者您建议需要实现的问题的解决方案。 这些不同于常规注释，因为它们是可操作的。 动作是FIXME： - 需要计算出来或TODO： - 需要实现。

  • 18.5 用// FIXME:给问题做注释

    class Calculator extends Abacus {
  constructor() {
    super();

    // FIXME: shouldn't use a global here
    total = 0;
  }
}

  • 18.6 用// TODO:去注释问题的解决方案

    class Calculator extends Abacus {
  constructor() {
    super();

    // TODO: total should be configurable by an options param
    this.total = 0;
  }
}

    类型定义

    类型定义 语法示例 解释
    String {string} --
    Number {number} --
    Boolean {boolean} --
    Object {Object} --
    Function {Function} --
    RegExp {RegExp} --
    Array {Array} --
    Date {Date} --
    单一类型集合 {Array.<string>} string 类型的数组
    多类型 {(number｜boolean)} 可能是 number 类型, 也可能是 boolean 类型
    允许为null {?number} 可能是 number, 也可能是 null
    不允许为null {!Object} Object 类型, 但不是 null
    Function类型 {function(number, boolean)} 函数, 形参类型
    Function带返回值 {function(number, boolean):string} 函数, 形参, 返回值类型
    Promise Promise.<resolveType, rejectType> Promise，成功返回的数据类型，失败返回的错误类型
    参数可选 @param {string=} name 可选参数, =为类型后缀
    可变参数 @param {...number} args 变长参数, ...为类型前缀
    任意类型 {*} 任意类型
    可选任意类型 @param {*=} name 可选参数，类型不限
    可变任意类型 @param {...*} args 变长参数，类型不限

  • 18.7 函数/方法/变量注释

    当 return 关键字仅作退出函数/方法使用时，无须对返回值作注释标识。

    参数和返回值注释必须包含类型信息，且不允许省略参数的说明。

    当函数是内部函数，外部不可访问时，可以使用 @inner 标识。

    示例：

    /**
 * 函数描述
 *
 * @param {string} p1 参数1的说明
 * @param {string} p2 参数2的说明，比较长
 *     那就换行了.
 * @param {number=} p3 参数3的说明（可选）
 * @return {Object} 返回值描述
 */
function foo(p1, p2, p3) {
    p3 = p3 || 10;
    return {
        p1: p1,
        p2: p2,
        p3: p3
    };
}

    重要的变量也需要和函数一样去进行注释，方便在其他地方引用的时候能随时看到注释（某些编辑器当鼠标在变量/函数上 hover 时会显示注释）。

  • 18.8 文件注释

    /**
 * @file Describe the file
 * @author author-name(mail-name@domain.com)
 *         author-name2(mail-name2@domain.com)
 */

# 注意事项

注释应该着重描述“做了什么”或“为什么这么做”而不是“怎么做”。

function objToUrlParam(obj = {}) {
    let param = ''
    for (let key in obj) {
        param += '&' + key + '=' + obj[key]
    }
    
    return param? '?' + param.substr(1) : ''
}

例如上面这个函数，你可以这样写注释：“将对象转化为 URL 参数”。也可以这样写：“首先遍历对象，获取每一个键值对，将它们拼在一起，最后在前面补个问号，变成 URL 参数”。

第一个注释描述做了什么（这么简单的函数可以不用注释）。第二个注释则描述了怎么做，事实上，这是一种多余的注释，或者说是垃圾注释。

回到顶部

← 空格 →