Javascript注释规范

最新推荐文章于 2024-08-24 22:35:39 发布

转载最新推荐文章于 2024-08-24 22:35:39 发布 · 941 阅读

文章标签：

#注释

JavaScript 专栏收录该内容

49 篇文章

订阅专栏

文件注释

文件注释位于文件的最前面，应包括文件的以下信息：

概要说明及版本（必须）
项目地址（开源组件必须）
版权声明（必须）
开源协议（开源组件必须）
版本号（必须）
修改时间（必须），以ISO格式表示（可使用Sublime Text的InsertDate插件插入）

文件注释必须全部以英文字符表示，并存在于文件的开发版本与生产版本中。例如：

/*!
 * jRaiser 2 Javascript Library
 * waterfall - v1.0.0 (2013-03-15T14:55:51+0800)
 * http://jraiser.org/ | Released under MIT license
 */

/*!
 * kan.56.com - v1.1 (2013-03-08T15:30:32+0800)
 * Copyright 2005-2013 56.com
 */

如果文件内包含了一些开源组件，则必须在文件注释中进行说明。例如：

/*!
 * jRaiser 2 Javascript Library
 * sizzle - v1.9.1 (2013-03-15T10:07:24+0800)
 * http://jraiser.org/ | Released under MIT license
 *
 * Include sizzle (http://sizzlejs.com/)
 */

普通注释

普通注释是为了帮助开发者和阅读者更好地理解程序，不会出现在API文档中。其中，单行注释以“//”开头；多行注释以“/*”开头，以“*/”结束。

普通注释的使用需遵循以下规定。

总是在单行注释符后留一个空格。例如：
```
// this is comment
```
总是在多行注释的结束符前留一个空格（使星号对齐）。例如：
```
/*
 */
```
不要把注释写在多行注释的开始符、结束符所在行。例如：
```
/* start

end */
```
```
/*
here is line 1
here is line 2
 */
```

不要编写无意义的注释。例如：

// 初始化value变量为0
var value = 0;

如果某段代码有功能未实现，或者有待完善，必须添加“TODO”标记，“TODO”前后应留一个空格。例如：
```
// TODO 未处理IE6-8的兼容性
function setOpacity(node, val) {
	node.style.opacity = val;
}
```

文档注释

文档注释将会以预定格式出现在API文档中。它以“/**”开头，以“*/”结束，其间的每一行均以“*”开头（均与开始符的第一个“*”对齐），且注释内容与“*”间留一个空格。例如：

/**
 * 把源对象的属性扩展到目标对象
 * @method extend
 * @param {Any} target 目标对象
 * @param {Any*} [source] 源对象。若有同名属性，则后者覆盖前者
 * @return {Any} 目标对象
 */

文档注释必须包含一个或多个以“@”开头的标签，标签用法见此页。