js/javascript代碼注釋規范與示例
注釋在代碼編寫過程中的重要性，寫代碼超過半年的就能深深的體會到。沒有注釋的代碼都不是好代碼。為了別人學習，同時為了自己以后對代碼進行‘升級’，看看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 1
here is line 2
*/
|
-
不要編寫無意義的注釋。例如：
|
1
2
|
// 初始化value變量為0
var
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 {屬性類型} 屬性名
*/
|