註釋

註釋是程式碼中最常見的組成部分。它們是另一種形式的文件，也是程式設計師最後才捨得花時間去寫的。但是，對於程式碼的總體可維護性而言，註釋是非常重要的一環。適度的添加註釋可以解釋說明程式碼的來龍去脈，其他開發者就可以不用從頭開始讀程式碼，而是直接去讀程式碼的任意部分。

JavaScript 支援兩種不同型別的註釋：單行註釋和多行註釋。

單行註釋

兩個斜線開始，至行尾結束。

// 這是一句單行註釋

【風格】：很多人喜歡在雙斜線之後敲入一個空格（我也喜歡），用來讓註釋文字有一定的偏移。

【使用方法】：

• 獨佔一行的註釋，用來解釋下一行程式碼。這行註釋之前總有一個空行，且縮排層級和下一行程式碼保持一致。
• 在程式碼行的尾部的註釋。程式碼結束到註釋之間至少有一個縮排。註釋（包括之前的程式碼部分）不應當超過單行最大字元數限制，如果超過了，就將這條註釋放置於當前程式碼行的上方。
• 被註釋掉的大段程式碼。

【注意】：單行註釋不應該以連續多行註釋的形式出現，除非你註釋掉一大段程式碼。

【示例】：

// 好的寫法
if (condition) {
    
    // 如果程式碼執行到這裡，則表明通過了所有安全性檢查
    allowed();
}

// 不好的寫法：註釋之前沒有空行
if (condition) {
    // 如果程式碼執行到這裡，則表明通過了所有安全性檢查
    allowed();
}

// 不好的寫法：錯誤的縮排
if (condition) {

// 如果程式碼執行到這裡，則表明通過了所有安全性檢查
    allowed();
}

// 好的寫法
var result = something + somethingElse; // somethingElse 不應當取值為 null

// 不好的寫法：程式碼和註釋之間沒有間隔
var result = something + somethingElse;// somethingElse 不應當取值為 null

// 好的寫法
// if (condition) {
//     doSomething();
//     thenDoSomethingElse();
// }

// 不好的寫法：這裡應當用多行註釋
// 接下來的這段程式碼非常難，那麼，讓我詳細解釋一下
// 這段程式碼的作用是首先判斷條件是否為真
// 只有為真時才會執行，這裡的條件是通過
// 多個函式計算出來的，在整個會話生命週期內
// 這個值是可以被修改的
if (condition) {
    // 如果程式碼執行到這裡，則表明通過了所有安全性檢查
    allowed();
}
 

多行註釋

多行註釋可以包裹跨行文字，以 /* 開始，以 */ 結束。

【示例】：多行註釋不僅僅可以用來包裹跨行文字，這取決於你。

/* 我的註釋 */
/* 另一段註釋
這段註釋包含兩行 */
/*
又是一段註釋
這段註釋同樣包含兩行
*/

【風格】：java 風格的多行註釋。

/*
 * 另一段註釋
 * 這段註釋包含兩行文字
 */

【說明】：至少包含三行，第一行為 /*，第二行開始以 * 開始且和上一行的 * 保持左對齊，最後一行為 */ 並且星號與之後的註釋說明文字間隔一個空格。

【使用方法】：
總是出現在將要描述的程式碼段之前，註釋和程式碼之間沒有空行間隔。和單行註釋一樣，在多行註釋之前應當有一個空行，且縮排層級和其描述的程式碼保持一致。

【示例】：

// 好的寫法
if (condition) {
    
    /*
     * 如果程式碼執行到這裡
     * 說明通過了所有的安全性檢查
     */
    allowed();
}

// 不好的寫法：註釋之前無空行
if (condition) {
    /*
     * 如果程式碼執行到這裡
     * 說明通過了所有的安全性檢查
     */
    allowed();
}

// 不好的寫法：星號後沒有空格
if (condition) {

    /*
     *如果程式碼執行到這裡
     *說明通過了所有的安全性檢查
     */
    allowed();
}

// 不好的寫法：錯誤的縮排
if (condition) {

/*
 * 如果程式碼執行到這裡
 * 說明通過了所有的安全性檢查
 */
    allowed();
}

// 不好的寫法：程式碼尾部註釋不要用多行註釋格式
var result = something + somethingElse; /* somethingElse 不應當取值為 null */

使用註釋

一種通行的指導原則是，當代碼不夠清晰時添加註釋，而當代碼很明瞭時不應當添加註釋。

【一般原則】：在需要讓程式碼變得更清晰時添加註釋。

難於理解的程式碼

難於理解的程式碼通常都應當添加註釋。根據程式碼的用途，可以用單行註釋、多行註釋，或是混用這兩種註釋。關鍵是讓其他人更容易讀懂這段程式碼。

可能被誤認為錯誤的程式碼

當代碼看上去有錯誤時，需要寫上註釋以防其他開發者好心進行“修復”。

瀏覽器特性 hack

JavaScript 程式設計師常常會編寫一些低效的、不雅的、徹頭徹尾的骯髒程式碼，用來讓低階瀏覽器正常工作。實際上這種情形是一種特殊的“可能被誤認為錯誤的程式碼”：這種不明顯的做瀏覽器特性 Hack 的程式碼可能隱含一些錯誤。

文件註釋

從技術角度來講，文件註釋並不是JavaScript的組成部分，但它們是一種普遍的實踐。

【風格】：JavaDoc 文件格式。

【格式】：多行註釋以單斜線加雙星號（/**）開始，接下來是描述資訊，其中使用@符號來表示一個或多個屬性。

【示例】：

/**
 ........
 @method merge
 @param {Object} 被合併的一個或多個物件
 @return {Object} 一個新的合併後的物件
 **/

【注意】：註釋的詳細格式和用法最終還是由你所選擇的文件生成工具決定的。

【需要添加註釋的內容】：

• 所有的方法：應當對方法、期望的引數和可能的返回值添加註釋描述。
• 所有的建構函式：應當對自定義型別和期望的引數添加註釋描述。
• 所有包含文件化方法的物件：如果一個物件包含一個或多個附帶文件註釋的方法，那麼這個物件也應當適當地針對文件生成工具新增文件註釋。