JavaScript注释规范

风格规范

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

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

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

	this.age = opts.age;

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

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

	/**
	 * [简要说明]
	 * @param
	 * @returns
	 */
	function doSth() {
		...
	}

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

文件注释

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

/**
 * Developer: totoroxiao
 * Date: 2019-03-18
 * [简要描述]
 */

文档注释

类注释

• @extends parent: 说明继承关系
• @private: 说明为私有成员
• @member {type} name desc: 说明类的成员属性

/**
 * [简要说明]
 * @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: 说明返回值类型、描述

/**
 * 获取时间戳
 * @param {Number|String} time Unix时间戳，或时间格式的字符串
 * @returns {Number|Null}
 */
function getTimestamp(time) {
	...
}

特殊标记注释

• FIXME: 注明需解决的问题
• TODO: 注明待办事项

// TODO: age应进行校验，避免非法取值
this.age = age;