陌上寒

陌上寒个人博客

javascript 代码规范(2)-注释规范

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

行内注释:

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

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

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

命名建议

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

示例:

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

单行注释:

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

语法:// 这是单行注释

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

示例:

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

多行注释:

说明:以 /* 开头, */ 结尾

语法/* 注释说明 */

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

示例:

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

 函数(方法)注释:

具体参考:JsDoc

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

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

注释名 语法 含义 示例
@param @param 参数名 {参数类型} 描述信息 描述参数的信息 @param name {String} 传入名称
@return @return {返回类型} 描述信息 描述返回值的信息 @return {Boolean} true:可执行;false:不可执行
@author @author 作者信息 [附属信息:如邮箱、日期] 描述此函数作者的信息 @author 张三 2015/07/21
@version @version XX.XX.XX 描述此函数的版本号 @version 1.0.3
@example @example 示例代码 演示函数的使用 @example setTitle(‘测试’)

示例:

// 不要这么做
// 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

JS 命名与注释规范详解

 

 

 

发表评论

电子邮件地址不会被公开。