注释在代码编写过程中的重要性，写代码超过半年的就能深深的体会到。没有注释的代码都不是好代码。为了别人学习，同时为了自己以后对代码进行‘升级’，看看js/javascript代码注释规范与示例。来自：http://www.56.com/style/-doc-/v1/tpl/js_dev_spec/spec-comment.html
文件注释
文件注释位于文件的最前面，应包括文件的以下信息：概要说明及版本（必须）项目地址（开源组件必须）版权声明（必须）开源协议（开源组件必须）版本号（必须）修改时间（必须），以ISO格式表示（可使用Sublime Text的InsertDate插件插入）文件注释必须全部以英文字符表示，并存在于文件的开发版本与生产版本中。例如：
|
1
2
3
4
5
|
/*! *
jRaiser 2 Javascript Library *
waterfall - v1.0.0 (2013-03-15T14:55:51+0800) *
http://jraiser.org/ | Released under MIT license */ |
|
1
2
3
4
|
/*! *
kan.56.com - v1.1 (2013-03-08T15:30:32+0800) *
Copyright 2005-2013 56.com */ |
如果文件内包含了一些开源组件，则必须在文件注释中进行说明。例如：
|
1
2
3
4
5
6
7
|
/*! *
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文档中。其中，单行注释以“//”开头；多行注释以“/*”开头，以“*/”结束。普通注释的使用需遵循以下规定。
-
总是在单行注释符后留一个空格。例如：
|
1
|
//
this is comment |
-
总是在多行注释的结束符前留一个空格（使星号对齐）。例如：
|
1
2
3
|
/* */ |
-
不要把注释写在多行注释的开始符、结束符所在行。例如：
|
1
2
3
|
/*
start end
*/ |
|
1
2
3
4
|
/*here
is line 1here
is line 2 */ |
-
不要编写无意义的注释。例如：
|
1
2
|
//
初始化value变量为0var value
= 0; |
-
如果某段代码有功能未实现，或者有待完善，必须添加“TODO”标记，“TODO”前后应留一个空格。例如：
|
1
2
3
4
|
//
TODO 未处理IE6-8的兼容性function setOpacity(node,
val) { node.style.opacity
= val;} |
文档注释
文档注释将会以预定格式出现在API文档中。它以“/**”开头，以“*/”结束，其间的每一行均以“*”开头（均与开始符的第一个“*”对齐），且注释内容与“*”间留一个空格。例如：
|
1
2
3
|
/** *
comment */ |
文档注释必须包含一个或多个注释标签。
-
@module。声明模块，用法：
|
1
2
3
4
|
/** *
模块说明 *
@module 模块名 */ |
例如：
|
1
2
3
4
|
/** *
Core模块提供最基础、最核心的接口 *
@module Core */ |
-
@class。声明类，用法：
|
1
2
3
4
5
|
/** *
类说明 *
@class 类名 *
@constructor */ |
@class必须搭配@constructor或@static使用，分别标记非静态类与静态类。
|
1
2
3
4
5
6
|
/** *
节点集合类 *
@class NodeList *
@constructor *
@param {ArrayLike<Element>} nodes 初始化节点 */ |
-
@method。声明函数或类方法，用法：
|
1
2
3
4
5
6
7
|
/** *
方法说明 *
@method 方法名 *
@for 所属类名 *
@param {参数类型} 参数名 参数说明 *
@return {返回值类型} 返回值说明 */ |
没有指定@for时，表示此函数为全局或模块顶层函数。当函数为静态函数时，必须添加@static；当函数有参数时，必须使用@param；当函数有返回值时，必须使用@return。
|
1
2
3
4
5
6
7
|
/** *
返回当前集合中指定位置的元素 *
@method *
@for NodeList *
@param {Number} [i=0] 位置下标。如果为负数，则从集合的最后一个元素开始倒数 *
@return {Element} 指定元素 */ |
-
@param。声明函数参数，必须与@method搭配使用。
-
当参数出现以下情况时，使用对应的格式：
|
1
|
[参数名] |
-
参数有默认值：
|
1
|
[参数名=默认值] |
@property。声明类属性，用法：
|
1
2
3
4
|
/** *
属性说明 *
@property {属性类型} 属性名 */ |