基于jsdoc的最优美的Javascript代码注释规范 js注释规范示例

一个优秀的程序员，必然有一个良好的代码写作习惯。希望大家都能养成好习惯！.如果看一个项目的代码没有任何注释规范，导致代码里很少有注释，或者注释写的很简练，那是一件多么让人难受的事情呀。

今天小编就对js注释规范进行总结：

本文js注释规范基于jsdoc，写出的代码注释能够成功生成注释文档。

命令名描述

@param @argument 指定参数名和说明来描述一个函数参数
@desc            描述
@returns         描述函数的返回值
@author          指示代码的作者
@deprecated      指示一个函数已经废弃，而且在将来的代码版本中将彻底删除。要避免使用这段代码
@see             创建一个HTML链接，指向指定类的描述
@version         指定发布版本
@requires        创建一个HTML链接，指向这个类所需的指定类
@throws @exception 描述函数可能抛出的异常的类型
{@link}          创建一个HTML链接，指向指定的类。这与@see很类似，但{@link}能嵌在注释文本中
@fileoverview    这是一个特殊的标记。如果在文件的第一个文档块中使用这个标记，则指定该文档块的余下部分将用来提
供这个文件的概述
@class       提供类的有关信息，用在构造函数的文档中
@constructor 明确一个函数是某个类的构造函数
@type        指定函数的返回类型
@extends     指示一个类派生了另一个类。JSDoc通常自己就可以检测出这种信息，不过，在某些情况下则必须使用这个标记
@private     指示一个类或函数是私有的。私有类和函数不会出现在HTML文档中，除非运行JSDoc时提供了–private命令行选项
@final       指示一个值是常量值。要记住JavaScript无法真正保证一个值是常量
@ignore JSDoc忽略有这个标记的函数

 

例子1：基本方法块注释 

/**
 * @description 加法运算
 * @method 方法名
 * @param {number} num1 加数
 * @param {number} num2 被加数
 * @return {number} result 结果
 */
function add(num1, num2){
    return num1 + num2;
}

常见的返回值有 string、boolean、number、object、array、function

如果方法的参数可选的情况，用 [data] 中括号表示

/**
 * @method 方法名
 * @param {number} [num] 中括号表示参数可选
 * @return {number} result 返回结果
 */
function getNumber(num){
    var retunNums = 0;    
    if (num != undefined) {
      retunNums = retunNums + 1;
    } else {
      retunNums = 1 + 2;
    }
    return retunNums;
}

如果方法的参数可选的情况，用 data = {} 表示

var defaultData = 1;
/**
 * @method 方法名
 * @param {number} num = defaultData 表示方法存在默认值
 * @return {number} result 返回结果
 */
function getNumber(num){
    var retunNums = 0;    
    if (num == undefined) {
      retunNums = defaultData;
    } else {
      retunNums = 1 + 2;
    }
    return retunNums;
}

如果方法的注释过长，可以用 <br> 来换行

/**
 * @method 方法名
 * @param {object} obj = {} 表示方法存在默认值 <br>
 * 例：
 *  {
 *    num: 1
 *  } 
 * @return {boolean} result 返回结果
 */
function getNumber(obj){
    ...
    return 返回;
}

 

例子二：文件注释

文件注释位于文件的最前面，应包括文件的以下信息：概要说明及版本（必须）项目地址（开源组件必须）版权声明（必须）开源协议（开源组件必须）版本号（必须）修改时间（必须），以ISO格式表示（可使用Sublime Text的InsertDate插件插入）文件注释必须全部以英文字符表示，并存在于文件的开发版本与生产版本中。例如：

/*!
 * web教程网
 * webcms - v1.0.0 (2018-03-15T14:55:51+0800)
 * http://www.jsphp.net/ | Released under MIT license
 */

/*!
 * web教程网
 * webcms - v1.0.0 (2018-03-15T14:55:51+0800)
 * Copyright 2018-2050 web教程网
 */

如果文件内包含了一些开源组件，则必须在文件注释中进行说明。例如：

/*!
 * web教程网
 * webcms - v1.0.1 (2018-10-15T10:07:24+0800)
 * Include jQuery (https://jquery.com/)
 */

 

例子3：变量注释，将关键的变量进行特殊注释

/**
 * @var {object}
 * @desc 变量定义
 * @property {string} json 属性 name 或者 name 属性 用户姓名
 * @property {string} 30   属性 age  或者 age  属性 用户年龄
 */
var userInfo = {
    name: 'json',
    age: '30'
}

 

例子4：常量注释，如果有默认值增加@default属性

/**
 * @constant {string}
 * @default #DDD
 * @desc 常量定义
 */
const COLOR_THEME = '#DDD';

 

例子5：枚举注释，用于url列表或者颜色枚举值，一般用于配置文件中

/**
 * @enum {number}
 * @desc cgi常见的返回码
 */ 
var RETCODE = { 
  /**
   * @desc 未登录
   */ NOT_LOGIN: 100000, /**
   * @desc 参数错误
   */ 
  PARAM_ERROR: 100001, 
  
  /**
   * @type {string}
   * @desc 未知错误
   */ 
  UNKOWN_ERROR: 'unkown' 
}

 

例子6：模块的注释 @module。声明模块，

/**
 * @desc 模块说明
 * @module 模块名 如：验证码模块
 */

// 例如：

/**
 * @desc Core模块提供最基础、最核心的接口
 * @module Core
 */

 

例子七：类的注释。 @class必须搭配@constructor或@static使用，分别标记非静态类与静态类。

/**
 * @desc 类说明
 * @constructor 非静态类与静态类
 * @class 类名 如：登录类
 */

 

例子八：类的属性。 @property。声明类属性

var LoginController = Core.extends({ 
     /**
     * @property {string}
     * @desc 这样标识类的属性
     */ 
     user : 'web教程网', 
     init: function() {} 
})

 

例子九：类的方法。@method。声明函数或类方法

/**
 * @desc 方法说明
 * @method 方法名
 * @for 所属类名
 * @param {参数类型} 参数名 参数说明
 * @return {返回值类型} 返回值说明
 */

没有指定@for时，表示此函数为全局或模块顶层函数。当函数为静态函数时，必须添加@static；当函数有参数时，必须使用@param；当函数有返回值时，必须使用@return。 

/**
 * @description 加法运算
 * @method 方法名
 * @for 所属类名
 * @param {number} num1 加数
 * @param {number} num2 被加数
 * @return {number} result 结果
 */
function add(num1, num2){
    return num1 + num2;
}

 

例子十：普通注释。

普通注释是为了帮助开发者和阅读者更好地理解程序，不会出现在API文档中。其中，单行注释以“//”开头；多行注释以“/*”开头，以“*/”结束。普通注释的使用需遵循以下规定。

总是在单行注释符后留一个空格。例如：

// web教程网 空格记得加

总是在多行注释的结束符前留一个空格（使星号对齐）。例如：

/*
                             
 */

不要把注释写在多行注释的开始符、结束符所在行。例如：

/* 不要在这里写注释 请写在下面
                             
不要在这里写注释 */

/*
 写描述
 写描述...
 */

 

例子十一：不要编写无意义的注释。

// 这个变量默认值为0
var num = 0;

 

例子十二：如果某段代码有功能未实现，或者有待完善，必须添加“TODO”标记，“TODO”前后应留一个空格。

// TODO 未处理IE6-8的兼容性
function setOpacity(node, val) {
    node.style.opacity = val;
}