JavaScript 代码注释规范

1. 文件头部注释

/**
 * @file 描述当前文件
 * @todo 接下来要开发的内容
 * @version 0.0.1 接下来要开发的内容
 * @author your name 接下来要开发的内容
 * @copyright 文件的版权信息
 * @version: 版本号
 * @createDate 文件创建时间
 * @license  文件许可证
 */

示例

/**
 * @file 常用工具库
 * @todo 将要开发密码的加密解密功能
 * @author 小淘气
 * @copyright 某某科技
 * @version 1.0.0
 * @createDate 2022-8-15 12:10:09
 */

2. 函数方法注释

/**
 * @method 描述方法
 * @desc 描述代码
 * @todo 接下来要开发的内容
 * @param {参数类型} 参数名 参数
 * @return {返回值类型} 返回值说明，无返回值：void
 * @callback 描述回调函数 回调函数说明
 * @example 示例说明
 */

示例

/**
 * @method login
 * @desc 登录并获取用户信息
 * @todo 登录之后要把数据进行处理
 * @param {String} username 用户名
 * @param {Number} password=123456 默认参数密码123456
 * @return void
 * @callback 登录成功后获取用户信息，并渲染页面
 * @example login('zhangsan',7777777)  // 返回 token 等信息
 */
function login(username,password,callback) {
  const USER_INFO = {username,password}
  callback(USER_INFO)
}

3. 变量、常量注释

/**
 * @var {变量类型} 变量名称
 * @constant {常量类型} 常量名称
 * @desc 变量描述
 * @default 变量默认值
 */

示例

/**
 * @var {String} username
 * @desc 用户名，变量注释
 * @default alias
 */
var username = 'alias'

/**
 * @constant {Object} USER_INFO
 * @desc 用户信息
 * @default {}
 */
const USER_INFO = {}

4. 单行注释

// 单行注释

5. 多行注释

/*
  多行注释
 */