json注释_十二个栗子对js注释规范进行总结-CSDN博客

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

好的规范规则让人舒服

以科学伦理学为例Science Ethics as an Illustration

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

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

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

例子二：文件注释

/*! * 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 空格记得加

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

/*                              */

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

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

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

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

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

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