第二章代碼註釋

時間 2020-12-13

標籤 javascript java 程序員瀏覽器函數工具測試 code 對象遞歸欄目 JavaScript 简体版

原文原文鏈接

註釋

註釋是代碼中最多見的組成部分.它們是另外一種形式的文檔,也是程序員最後才捨得去寫的javascript

單行註釋

獨佔一行的註釋, 用來解釋下一行代碼.這行註釋以前老是有一個空行,且縮進層級和下一代碼保持一致
在代碼行的尾部註釋.代碼結束到註釋之間至少有一個縮進.註釋(包括以前的代碼部分),不該該超過單行最大註釋,若是超過,這條註釋就應該放置在當前代碼行的上方
被註釋掉的大段代碼

// 好的寫法
if (bol) {
    
    // 這裏是代碼註釋
    test();
}


// 很差的寫法: 註釋以前沒有空行
if (bol) { 
    // 這裏是代碼註釋
    test();
}

// 很差得寫法: 錯誤的縮進
if (bol) { 
    
// 這裏是代碼註釋
    test();
}



// 好的寫法
var result = something + somethingElse; // somethingElse不該當爲null



// 很差的寫法: 代碼和註釋之間沒有空格
var result = something + somethingElse;// somethingElse不該當爲null

// 好的寫法
// if (bol) {  
//     test();
// }


// 很差的寫法: 應該使用多行註釋
// 接下來的有點難
// 我來解一下
// 先這樣
// 而後那樣
// 而後再這樣
if (bol) {  
    test();
}

多行註釋

它以/*開始,以*/結束java

var result = something + somethingElse;// somethingElse不該當爲null// 好的寫法
if (bol) {  
    
   /*
    * 這個是一個多行註釋
    * 這個是第二行
    */
    test();
}


// 很差的寫法: 註釋前沒有空行
if (bol) {   
   /*
    * 這個是一個多行註釋
    * 這個是第二行
    */
    test();
}

// 很差的寫法: 星號後沒有空格
if (bol) {  
    
   /*
    *這個是一個多行註釋
    *這個是第二行
    */
    test();
}



// 很差的寫法: 錯誤的縮進
if (bol) {  
    
/*
 *這個是一個多行註釋
 *這個是第二行
 */
    test();
}


// 很差的寫法: 行尾不適合使用多行註釋
var result = something + somethingElse; /* somethingElse不該當爲null */

使用註釋

什麼時候添加註釋是程序員常常討論的一個話題. 一種同行的指導原則是,當代碼不夠清晰的時候添加註釋,而當代碼很明瞭的時候不該當添加註釋.程序員

// 很差的寫法
// 初始化count
var count = 10;


// 好的寫法
// 改變這個值可能會讓它變成青蛙
var count = 10;

難於理解的代碼

難於理解的代碼應該加上註釋.根據代碼的用途,你能夠用單行註釋/多行註釋,或者混用兩種註釋.關鍵是讓其餘人更容易讀懂這段代碼瀏覽器

// 好的寫法
if(mode){
    
    /*
     * 當mode爲2時(原型到原型,對象到對象),這裏只遞歸執行一次
     * 用來執行原型到原型,對象到對象的都合併操做
     * 將會被掛起,在合適的時機執行
     */
    if(mode === 2) {
        Y.mix(...)
    }
}

可能被誤認爲是錯誤的代碼

while (element && (element = element[axis])){  // 提示: 賦值操做
    if( (all || element[TAG_NAME]) && (!fn || fn(element))){
        return element;
    }
}

這個例子中,開發者在while循環控制條件中使用了一個賦值運算符.這不是一種標準的用法,並經常被檢測工具認爲有問題的.若是你對這個代碼不熟悉,誤覺得是錯誤,加上了註釋,就不會有這種誤解了函數

瀏覽器特性hack

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);
    }
}
// ....省略

文檔註釋

從技術的角度講, 文檔註釋並非JavaScript的組成部分,但它們是一種廣泛的實踐工具

/*
* 這個函數是用來測試文檔註釋的
* 這個函數是有幾個參數
* 一個是這個,一個是哪一個
* @method test
* @params {String}  一個文字
* @params {Object}  一個對象
* @return {Object}  返回一個對象
*/
var test = function (message, obj) {
    return {
        message: message,
        obj: obj
    }
}