js/javascript代碼注釋規范與示例


 

文件注釋

 文件注釋位於文件的最前面,應包括文件的以下信息:概要說明及版本(必須)項目地址(開源組件必須)版權聲明(必須)開源協議(開源組件必須)版本號(必須)修改時間(必須),以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文檔中。它以“/**”開頭,以“*/”結束,其間的每一行均以“*”開頭(均與開始符的第一個“*”對齊),且注釋內容與“*”間留一個空格。例如:

 

/* *

 * comment

 
*/

 

文檔注釋必須包含一個或多個注釋標簽。
  •  @module。聲明模塊,用法:

    /* *

     * 模塊說明

     * @module 模塊名

     
    */

     

    例如:
    /* *

     * Core模塊提供最基礎、最核心的接口

     * @module Core

     
    */

@class。聲明類,用法:

 

/* *

 * 類說明

 * @class 類名

 * @constructor

 
*/

 

@class必須搭配@constructor或@static使用,分別標記非靜態類與靜態類。

 

/* *

 * 節點集合類

 * @class NodeList

 * @constructor

 * @param {ArrayLike<Element>} nodes 初始化節點

 
*/

 

@method。聲明函數或類方法,用法:

 

/* *

 * 方法說明

 * @method 方法名

 * @for 所屬類名

 * @param {參數類型} 參數名 參數說明

 * @return {返回值類型} 返回值說明

 
*/

 

沒有指定@for時,表示此函數為全局或模塊頂層函數。當函數為靜態函數時,必須添加@static;當函數有參數時,必須使用@param;當函數有返回值時,必須使用@return。

 

/* *

 * 返回當前集合中指定位置的元素

 * @method

 * @for NodeList

 * @param {Number} [i=0] 位置下標。如果為負數,則從集合的最后一個元素開始倒數

 * @return {Element} 指定元素

 
*/

 

@param。聲明函數參數,必須與@method搭配使用。

 當參數出現以下情況時,使用對應的格式:

 

[參數名]

 

 參數有默認值:

 

[參數名=默認值]

 

@property。聲明類屬性,用法:

 

/* *

 * 屬性說明

 * @property {屬性類型} 屬性名

 
*/

 


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM