摘要：注釋是代碼中最常見的組成部分它們是另一種形式的文檔也是程序員最后才舍得花時間去寫的但是對于代碼的總體可維護性而言注釋是非常重要的一環打開一個沒有任何注釋的文件就好像趣味冒險但如果給你的時間有限這項任務就變成了折磨適度的添加注釋可以解釋說明代

注釋是代碼中最常見的組成部分.它們是另一種形式的文檔,也是程序員最后才舍得花時間去寫的.但是,對于代碼的總體可維護性而言,注釋是非常重要的一環.打開一個沒有任何注釋的文件就好像趣味冒險,但如果給你的時間有限,這項任務就變成了折磨.適度的添加注釋可以解釋說明代碼的來龍去脈,其他開發者就可以不用從頭開始閱讀代碼,而是直接去讀代碼的任意部分.編程風格通常不會包含對注釋的風格約定,但我任務從注釋的作用即可看出它們的重要性不容忽視.

js支持兩種不同類型的注釋: 單行注釋和多行注釋.

2.1 單行注釋
單行注釋有三種使用方法:

獨占一行的注釋,用來解釋下一行代碼.這行注釋之前總是有一個空行,且縮進層級和下級代碼保持一致.

在代碼行的尾部的注釋.代碼結束到注釋之間至少有一個縮進.注釋(包括之前的代碼部分)不應當超過單行最大字符數限制,如果超過了,就將這條注釋放置于當前代碼行的上方.

被注釋掉的大段代碼(很多編輯器都可以批量注釋掉多行代碼).

單行注釋不應當以連續多行注釋的形式出現,除非你注釋掉一大段代碼.只有當需要注釋一段很長的文本是才使用多行注釋.

// 好的寫法
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();
}

2.2 多行注釋

// 合法的多行注釋
/* 我的注釋 */
/* 另一段注釋
這段注釋包含兩行*/
/*
又是一段注釋
這段注釋同樣包含兩行
*/

//逼格高,更加清晰.java風格注釋
/*
 * 另一段注釋
 * 這段注釋包含兩行文本
 */

多行注釋總是會出現在將要描述的代碼段之前, 注釋和代碼之間沒有空行間隔. 和單行注釋一樣, 多行注釋之前應當有一個空行, 且縮進層級和其描述的代碼保持一致.

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

// 不好的寫法: 注釋之前無空行
if(condition){
    /*
     * 如果代碼段執行到這里
     * 說明通過了所有的安全性檢測
     */
    allowed();
}

// 不好的寫法: 星號后沒有空格
if(condition){
    /*
     *如果代碼段執行到這里
     *說明通過了所有的安全性檢測
     */
    allowed();
}

// 不好的寫法: 錯誤的縮進
if(condition){

/*
 * 如果代碼段執行到這里
 * 說明通過了所有的安全性檢測
 */
    allowed();
}

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

2.3 使用注釋
通行的指導原則是：當代碼不夠清晰時添加注釋, 當代碼很明了時不應該添加注釋.

2.3.1 難于理解的代碼
難于理解的代碼通常都應該添加注釋. 根據代碼的用途, 你可以用單行注釋, 多行注釋, 或是混合兩種注釋. 關鍵是讓其他人更容易讀懂這段代碼. 比如, 這段實例代碼摘自YUI類庫中的Y.mix()方法.

// 好的寫法
if(mode) {

    /*
     * 當mode為2時(原型到原型, 對象到對象), 這里只遞歸執行一次
     * 用來執行原型到原型的合并操作, 對象到對象的合并操作 
     * 將會被掛起, 在合適的時機執行
     */
    if(mode === 2) {
        Y.mix(receiver.prototype, supplier.prototype, overwrite,
                whitelist, 0, merge);
    }
    
    /*
     * 根據指定的模式類型, 我們可能會從元對象拷貝至原型中,
     * 或是從原型拷貝至接受對象中
     */
    from = mode === 1 || mode === 3 ? supplier.prototype : supplier;
    to = mode === 1 || mode === 4 ? receiver.prototype : receiver;
    
    /*
     * 如果supplier或receiver不含有原型屬性時,
     * 則邏輯結束, 并返回undefined, 如果有原型屬性,
     * 則邏輯結束并返回received
     */
    if(!from || !to) {
        return receiver;
    }
}else {
    from = supplier;
    to = receiver;
}

Y.mix()方法使用常量來決定如何處理. mode參數就是常量之一, 但僅僅通過這些數值無法解釋他們各自代表的含義. 這里的注釋非常棒, 因為它及時地解釋了這里負責的決策邏輯.

2.3.2 可能被誤認為錯誤的代碼
另一個適合添加注釋的好時機是當代碼看上去有錯誤時. 在團隊開發中, 總是會有一些好心的開發者在編輯代碼時發現他人的代碼錯誤, 就立即修復. 有時這段代碼并不是錯誤的源頭, 所以"修復"這個錯誤往往會制造其他的錯誤, 因此本次修改應當是可追蹤的. 當你寫的代碼有可能會被別的開發者任務是有錯誤時, 則需要添加注釋.

while(element && (element = element[axis])) {
    if((all || element[]TAG_NAME) &&
            (!fn || fn(elemtnt))) {
        return element;
    }
}

這個例子中, 開發者在while循環控制條件中使用了一個賦值運算符. 這不是一種標準用法, 并常常被檢測工具認為是有問題的. 如果你對這段代碼不熟悉, 讀到這段沒有注釋的代碼時, 很有可能誤認為這是一個錯誤, 猜想作者的本意是使用比較運算符==而不是賦值運算符=. 這行末尾的注釋說明作者是有意為之, 即賦值而非比較. 這樣, 其他開發者讀到這段代碼時就不會將它"修復".

2.3.3 瀏覽器特性hack
js程序員常常會編寫一些低效的、不雅的、徹頭徹尾的臟代碼, 用來讓低級瀏覽器正常工作. 實際上這種情形是一種特殊的"可能被誤認為錯誤的代碼": 這種不明顯的做瀏覽器特性Hack的代碼可能隱含一些錯誤. 例子, 摘自YUI類庫的Y.DOM.contains()方法.

var ret = false;

if(!needle || !element || !needle[NODE_TYPE] || !element[NODE_TYPE]) {
    ret = false;
}else if(element[CONTAINS]) {
    
    //如果needle不是ELEMENT_NODE時, ie和safari下面會有錯誤
    if(Y.UA.opera || needle[NODE_TYPE] === 1) {
        ret = element[CONTAINS](needle);
    }else {
        ret = Y_DOM._bruteContains(element, needle);
    }
}else if(element[COMPARE_DOCUMENT_POSITION]) {
    if(element === needle ||
            !!(element[COMPARE_DOCUMENT_POSITION](needle) & 16)){
        ret = true;
    }
}

return ret;

這段代碼第7行包含一條很重要的注釋. 盡管IE和Safari中都有內置方法contains(), 但如果needle不是一個元素時, 這個方法會報錯. 所以只有當瀏覽器是Opera時才能用這個方法, 其他瀏覽器中needle必須是一個元素(nodeType是1). 這里關于瀏覽器的說明同樣解釋了為什么需要一個if語句, 這個注釋不僅確保將來不會被他人誤改動, 而且在代碼編寫者回頭閱讀自己這段代碼時, 也會適當的針對新版本的IE和Safari的兼容情況作出調整.

2.4 文檔注釋
文檔注釋并不是js的組成部分, 但是應用很廣泛. 最流行的格式是JavaDoc文檔格式: 多行注釋以單斜線加雙星號(/**)開始, 接下來是描述信息, 其中使用@符號來表示一個或多個屬性.

/**
如果需要深拷貝(deep copy), 請使用"clone()"
@method merge
@param {Object} 被合并的一個或多個對象
@return {Object} 一個新的合并后的對象
**/
Y.merge = function() {
    var args = arguments,
        i = 0,
        len = args.length,
        result = {};
        
    for(; i < len; ++i) {
        Y.mix(result, args[i], true);
    }
    
    return result;
}

所有的方法

應當對方法、期望的參數和可能返回的值添加注釋描述.

所有的構造函數

應當對自定義類型和期望的參數添加注釋描述.

所有包含文檔化方法的對象

如果一個對象包含一個或多個附帶文檔注釋的方法, 那么這個對象也應當適當地針對文檔生成工具添加文檔注釋