JavaScript 註釋規範

HTML與CSS都有註釋，但是這兩者的註釋比JavaScript註釋要簡單的多。

主要原因是因為HTML和CSS程式碼相對比較簡單，它們都算不上真正的程式語言。

面對結構龐大且繁雜的JavaScript程式碼，較為科學的註釋更有利於專案的團隊開發，後期維護也會便利。

下面分佈介紹一下注釋的總體原則、註釋的基本語法和對常見語法結構的註釋規則推薦。

一.註釋總體原則：

能不註釋，儘量不對程式碼新增註釋，以減少體積。

如果必須要註釋，則註釋必須詳盡，格式科學，提高程式碼的可讀性。

也就是說註釋並不是用來美化程式碼的，而是為了便於自己活著其他程式設計師的閱讀便利性。

它是一種負擔，但是為了團隊開發等目的又是必要的。

二.單行註釋：

兩個斜槓//可以建立一個單行註釋，斜槓後面要增加一個空格，緊接著是註釋內容。

註釋的縮排需要與所註釋的程式碼一致，且要位於被註釋程式碼的上面。

程式碼演示如下：

[JavaScript] 純文字檢視 複製程式碼
// 螞蟻部落教程測試函式
function func() {
  // 用來儲存定時器函式標識
  let flag = null;
}

三.多行註釋：

/**/可以建立多行註釋，也就是以"/*"開始，"*/"結束，中間是註釋內容。

既然是多行註釋，自然被註釋的內容是可以換行的。

儘量使用單行註釋替代多行註釋，如果註釋函式，推薦使用多行註釋。

四.函式的註釋：

函式是使用最為頻繁的語法結構，相對較為複雜，所以良好的註釋對於理解函式的功能非常有必要。

註釋格式如下：

[JavaScript] 純文字檢視 複製程式碼
/*方法說明
 *@method 方法名
 *@for 所屬類名
 *@param{引數型別}引數名 引數說明
 *@return {返回值型別} 返回值說明
*/

可以看到在註釋的開始於結尾分別是/*與*/，具體的註釋內容前面也帶有一個星號，看起來更加整齊。

看一段簡單的註釋程式碼例項：

[JavaScript] 純文字檢視 複製程式碼
/*函式說明
 * @param {string} p1 引數1的說明
 * @param {string} p2 引數2的說明，比較長
 *     那就換行了.
 * @param {number=} p3 引數3的說明（可選）
 * @return {Object} 返回值描述
 */
 function foo(p1, p2, p3) {
  var p3 = p3 || 10;
  return {
    p1: p1,
    p2: p2,
    p3: p3
  };
}

五.模組註釋：

模組註釋格式如下：

[JavaScript] 純文字檢視 複製程式碼
/* 模組說明
* @module 模組名
*/

六.class類註釋：

ES2015新增類的概念，具體參閱JavaScript class 類一章節。

類的註釋格式如下：

[JavaScript] 純文字檢視 複製程式碼
/* 類說明
 * @class 類名
 * @constructor
 */

由於類分為靜態類與非靜態類，所以@class需要與@constructor或者@static配合使用。

七.註釋內容：

知道為什麼需要註釋，那麼也就知道註釋應該怎麼寫。

註釋的目的是告訴閱讀者不宜察覺或者不易獲取到的資訊，而不是一目瞭然的東西。

下面的註釋就相當於廢話，根本就不需要：

[JavaScript] 純文字檢視 複製程式碼
// 宣告一個變數timer
let timer=null;

只要不是JavaScript盲，都能知道上面是宣告一個變數，根本用不著註釋。

應該強調tmer這個變數將來要發揮的作用，程式碼修改如下：

[JavaScript] 純文字檢視 複製程式碼
// 宣告變數用來儲存定時器函式的標識
let timer=null;

八.待辦內容：

可能有些地方的程式碼待編寫或者有些功能待實現。

那麼可以使用// TODO標識出來，格式如下：

[JavaScript] 純文字檢視 複製程式碼
// TODO: 標註待實現的功能。

九.有bug待處理：

如果程式碼有些地方需要優化，甚至程式碼中存在錯誤去修正。

那麼可以使用// FIXME標註出來，格式如下：

[JavaScript] 純文字檢視 複製程式碼
// FIXME: 標註出現的問題。

上面介紹的僅是常見的註釋，JavaScript語法結構很多，感興趣的朋友可以自行總結。