注釋

注釋是代碼中最常見的組成部分.它們是另一種形式的檔案,也是程式員最后才舍得去寫的

單行注釋

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

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

多行注釋

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

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
    }
}

所有的方法

應當對方法,期望的引數和可能回傳的回傳值添加注釋描敘

所有的建構式

應當對自定義型別和期望的引數添加注釋描敘

所有包含檔案化的物件

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

轉載請註明出處，本文鏈接：https://www.uj5u.com/qiye/233857.html

標籤：JavaScript

上一篇：第一章代碼基本的格式化

下一篇：前言

第二章 代碼注釋

注釋