JavaScript 注释规范

风格规范

  • 行内注释：行末，与代码之间一个空格，//与注释文字之间一个空格

    1
    this.name = opts.name; // name赋值

  • 单行注释：代码行前一行，上方需有空行，//与注释文字之间一个空格

    1
    2
    3
    4
    this.age = opts.age;

    // name赋值
    this.name = opts.name;

  • 多行注释：/* */注释，风格如下：

    1
    2
    3
    4
    5
    6
    7
    8
    /**
     * [简要说明]
     * @param
     * @returns
     */
    function doSth() {
    	...
    }

  • 原则：如非必要勿添加，如有必要需详尽

文件注释

新建文件时，在文件头部注明开发者和日期，也可增加一行对该文件的简要描述。

1
2
3
4
5
/**
 * Developer: totoroxiao
 * Date: 2019-03-18
 * [简要描述]
 */

文档注释

类注释

  • @extends parent: 说明继承关系
  • @private: 说明为私有成员
  • @member {type} name desc: 说明类的成员属性 
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    /**
     * [简要说明]
     * @extends Animal
     */
    class Person extends Animal {
    	/**
    	 * [简要说明]
    	 * @constructor
    	 * @param {Object} options 配置参数
    	 * @param {String} options.name 姓名
    	 */
    	constructor(options) {
    		options = options || {};
    		/** @member {String} Person.name 一个人的姓名 */
    		this.name = options.name;
    	}

    	/**
    	 * 公开方法
    	 * @returns {String}
    	 */
    	getName() {
    		return this.name;
    	}

    	/**
    	 * 私有方法
    	 * @private
    	 */
    	_sleep() {}
    }

函数注释

  • @param {type} name desc: 说明参数类型、名称、描述
  • @returns {type} desc: 说明返回值类型、描述
    1
    2
    3
    4
    5
    6
    7
    8
    /**
     * 获取时间戳
     * @param {Number|String} time Unix时间戳，或时间格式的字符串
     * @returns {Number?}
     */
    function getTimestamp(time) {
    	...
    }

特殊标记注释

  • FIXME: 注明需解决的问题
  • TODO: 注明待办事项
    1
    2
    // TODO: age应进行校验，避免非法取值
    this.age = age;