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 {屬性類型} 屬性名

  */