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

来源:网络 文章列表 2018-11-28 8
一个优秀的程序员,必然有一个良好的代码写作习惯。希望大家都能养成好习惯!.如果看一个项目的代码没有任何注释规范,导致代码里很少有注释,或者注释写的很简练,那是一件多么让人难受的事情呀。本文js注释规范基于jsdoc,写出的代码注释能够成功生成注释文档。

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

今天小编就对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;
}

 

版权声明

本站部分原创文章,部分文章整理自网络。如有转载的文章侵犯了您的版权,请联系站长删除处理。如果您有优质文章,欢迎发稿给我们!联系站长:
愿本站的内容能为您的学习、工作带来绵薄之力。

评论

  • 随机获取
点击刷新
精彩评论
关闭