摘要：注釋是代碼中最常見(jiàn)的組成部分它們是另一種形式的文檔也是程序員最后才舍得花時(shí)間去寫(xiě)的但是對(duì)于代碼的總體可維護(hù)性而言注釋是非常重要的一環(huán)打開(kāi)一個(gè)沒(méi)有任何注釋的文件就好像趣味冒險(xiǎn)但如果給你的時(shí)間有限這項(xiàng)任務(wù)就變成了折磨適度的添加注釋可以解釋說(shuō)明代

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

js支持兩種不同類(lèi)型的注釋: 單行注釋和多行注釋.

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

獨(dú)占一行的注釋,用來(lái)解釋下一行代碼.這行注釋之前總是有一個(gè)空行,且縮進(jìn)層級(jí)和下級(jí)代碼保持一致.

在代碼行的尾部的注釋.代碼結(jié)束到注釋之間至少有一個(gè)縮進(jìn).注釋(包括之前的代碼部分)不應(yīng)當(dāng)超過(guò)單行最大字符數(shù)限制,如果超過(guò)了,就將這條注釋放置于當(dāng)前代碼行的上方.

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

單行注釋不應(yīng)當(dāng)以連續(xù)多行注釋的形式出現(xiàn),除非你注釋掉一大段代碼.只有當(dāng)需要注釋一段很長(zhǎng)的文本是才使用多行注釋.

// 好的寫(xiě)法
if(condition){
    
    // 如果代碼執(zhí)行到這里,則表明通過(guò)了所有安全性檢查
    allowed();
}

// 不好的寫(xiě)法
if(condition){
    // 如果代碼執(zhí)行到這里,則表明通過(guò)了所有安全性檢查
    allowed();
}

// 不好的寫(xiě)法: 錯(cuò)誤的縮進(jìn)
if(condition){
// 如果代碼執(zhí)行到這里,則表明通過(guò)了所有安全性檢查
    allowed();
}

// 好的寫(xiě)法
var result = something + somethingElse; // somethingElse不應(yīng)當(dāng)取值為null

// 不好的寫(xiě)法: 代碼和注釋之間沒(méi)有間隔
var result = something + somethingElse;// somethingElse不應(yīng)當(dāng)取值為null

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

// 不好的寫(xiě)法
// 接下來(lái)這段代碼非常難, 那么, 讓我詳細(xì)解釋一下
// 這段代碼的作用是首先判斷天劍是否為真
// 只有為真時(shí)才會(huì)執(zhí)行, 這里的條件是通過(guò)
// 多個(gè)函數(shù)計(jì)算出來(lái)的, 在整個(gè)回話生命周期內(nèi)
// 整個(gè)值是可以被修改的
if(condition) {
    
    // 如果代碼執(zhí)行到這里, 則表明通過(guò)了所有安全性檢查
    allowed();
}

2.2 多行注釋

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

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

多行注釋總是會(huì)出現(xiàn)在將要描述的代碼段之前, 注釋和代碼之間沒(méi)有空行間隔. 和單行注釋一樣, 多行注釋之前應(yīng)當(dāng)有一個(gè)空行, 且縮進(jìn)層級(jí)和其描述的代碼保持一致.

// 好的寫(xiě)法
if(condition){
    
    /*
     * 如果代碼段執(zhí)行到這里
     * 說(shuō)明通過(guò)了所有的安全性檢測(cè)
     */
    allowed();
}

// 不好的寫(xiě)法: 注釋之前無(wú)空行
if(condition){
    /*
     * 如果代碼段執(zhí)行到這里
     * 說(shuō)明通過(guò)了所有的安全性檢測(cè)
     */
    allowed();
}

// 不好的寫(xiě)法: 星號(hào)后沒(méi)有空格
if(condition){
    /*
     *如果代碼段執(zhí)行到這里
     *說(shuō)明通過(guò)了所有的安全性檢測(cè)
     */
    allowed();
}

// 不好的寫(xiě)法: 錯(cuò)誤的縮進(jìn)
if(condition){

/*
 * 如果代碼段執(zhí)行到這里
 * 說(shuō)明通過(guò)了所有的安全性檢測(cè)
 */
    allowed();
}

// 不好的寫(xiě)法: 代碼尾部注釋不要用多行注釋格式
var result = something + somethingElse; /*somethingElse 不應(yīng)當(dāng)取值為null*/

2.3 使用注釋
通行的指導(dǎo)原則是：當(dāng)代碼不夠清晰時(shí)添加注釋, 當(dāng)代碼很明了時(shí)不應(yīng)該添加注釋.

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

// 好的寫(xiě)法
if(mode) {

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

Y.mix()方法使用常量來(lái)決定如何處理. mode參數(shù)就是常量之一, 但僅僅通過(guò)這些數(shù)值無(wú)法解釋他們各自代表的含義. 這里的注釋非常棒, 因?yàn)樗皶r(shí)地解釋了這里負(fù)責(zé)的決策邏輯.

2.3.2 可能被誤認(rèn)為錯(cuò)誤的代碼
另一個(gè)適合添加注釋的好時(shí)機(jī)是當(dāng)代碼看上去有錯(cuò)誤時(shí). 在團(tuán)隊(duì)開(kāi)發(fā)中, 總是會(huì)有一些好心的開(kāi)發(fā)者在編輯代碼時(shí)發(fā)現(xiàn)他人的代碼錯(cuò)誤, 就立即修復(fù). 有時(shí)這段代碼并不是錯(cuò)誤的源頭, 所以"修復(fù)"這個(gè)錯(cuò)誤往往會(huì)制造其他的錯(cuò)誤, 因此本次修改應(yīng)當(dāng)是可追蹤的. 當(dāng)你寫(xiě)的代碼有可能會(huì)被別的開(kāi)發(fā)者任務(wù)是有錯(cuò)誤時(shí), 則需要添加注釋.

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

這個(gè)例子中, 開(kāi)發(fā)者在while循環(huán)控制條件中使用了一個(gè)賦值運(yùn)算符. 這不是一種標(biāo)準(zhǔn)用法, 并常常被檢測(cè)工具認(rèn)為是有問(wèn)題的. 如果你對(duì)這段代碼不熟悉, 讀到這段沒(méi)有注釋的代碼時(shí), 很有可能誤認(rèn)為這是一個(gè)錯(cuò)誤, 猜想作者的本意是使用比較運(yùn)算符==而不是賦值運(yùn)算符=. 這行末尾的注釋說(shuō)明作者是有意為之, 即賦值而非比較. 這樣, 其他開(kāi)發(fā)者讀到這段代碼時(shí)就不會(huì)將它"修復(fù)".

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

var ret = false;

if(!needle || !element || !needle[NODE_TYPE] || !element[NODE_TYPE]) {
    ret = false;
}else if(element[CONTAINS]) {
    
    //如果needle不是ELEMENT_NODE時(shí), ie和safari下面會(huì)有錯(cuò)誤
    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中都有內(nèi)置方法contains(), 但如果needle不是一個(gè)元素時(shí), 這個(gè)方法會(huì)報(bào)錯(cuò). 所以只有當(dāng)瀏覽器是Opera時(shí)才能用這個(gè)方法, 其他瀏覽器中needle必須是一個(gè)元素(nodeType是1). 這里關(guān)于瀏覽器的說(shuō)明同樣解釋了為什么需要一個(gè)if語(yǔ)句, 這個(gè)注釋不僅確保將來(lái)不會(huì)被他人誤改動(dòng), 而且在代碼編寫(xiě)者回頭閱讀自己這段代碼時(shí), 也會(huì)適當(dāng)?shù)尼槍?duì)新版本的IE和Safari的兼容情況作出調(diào)整.

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

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

所有的方法

應(yīng)當(dāng)對(duì)方法、期望的參數(shù)和可能返回的值添加注釋描述.

所有的構(gòu)造函數(shù)

應(yīng)當(dāng)對(duì)自定義類(lèi)型和期望的參數(shù)添加注釋描述.

所有包含文檔化方法的對(duì)象

如果一個(gè)對(duì)象包含一個(gè)或多個(gè)附帶文檔注釋的方法, 那么這個(gè)對(duì)象也應(yīng)當(dāng)適當(dāng)?shù)蒯槍?duì)文檔生成工具添加文檔注釋