javascript 代码规范（2）-注释规范

js 支持三种不同类型的注释：行内注释、单行注释和多行注释：

行内注释：

说明：行内注释以两个斜线开始，以行尾结束。

语法：code // 这是行内注释

使用方式：//(双斜线)与代码之间保留一个空格，并且//(双斜线)与注释文字之间保留一个空格。

命名建议：

// 用来显示一个解释的评论
// -> 用来显示表达式的结果，
// >用来显示 console 的输出结果，

示例：

function test() { // 测试函数
  console.log('Hello World!'); // >Hello World!
  return 3 + 2; // ->5
}

单行注释：

说明：单行注释以两个斜线开始，以行尾结束。

语法：// 这是单行注释

使用方式：单独一行：//(双斜线)与注释文字之间保留一个空格。

示例：

// 调用了一个函数；1)单独在一行
setTitle();

多行注释：

说明：以?/*?开头，?*/?结尾

语法：/* 注释说明 */

使用方法：若开始/*和结束*/都在一行，推荐采用单行注释。若至少三行注释时，第一行为/*，最后行为*/，其他行以*开始，并且注释文字与*保留一个空格。

示例：

/*
* 代码执行到这里后会调用setTitle()函数
* setTitle()：设置title的值
*/
setTitle();

?函数(方法)注释：

具体参考：JsDoc

使用?/** ... */?作为多行注释。包含描述、指定所有参数和返回值的类型和值。

(只列出一部分，并不是全部)

示例：

// 不要这么做
// make() returns a new element
// based on the passed in tag name
//
// @param {String} tag
// @return {Element} element
function make(tag) {

  // ...stuff...

  return element;
}

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

  // ...stuff...

  return element;
}

参考地址：

javascript-style-guide