提升代碼可讀性的十大註釋技巧分享

不少程序員在寫代碼的時候每每都不注意代碼的可讀性，讓別人在閱讀代碼時花費更多的時間。其實，只要程序員在寫代碼的時候，注意爲代碼加註釋，並以合理的格式爲代碼加註釋，這樣就方便別人查看代碼，也方便本身之後查看了。下面分享十個加註釋的技巧：

1. 逐層註釋

爲每一個代碼塊添加註釋，並在每一層使用統一的註釋方法和風格。例如：

針對每一個類：包括摘要信息、做者信息、以及最近修改日期等；

針對每一個方法：包括用途、功能、參數和返回值等。

在團隊工做中，採用標準化的註釋尤其重要。固然，使用註釋規範和工具(例如C#裏的XML，Java裏的Javadoc)能夠更好的推進註釋工做完成得更好。

2. 使用分段註釋

若是有多個代碼塊，而每一個代碼塊完成一個單一任務，則在每一個代碼塊前添加一個註釋來向讀者說明這段代碼的功能。例子以下：

// Check that all data records
// are correct
foreach (Record record in records)
... {
    if (rec.checkStatus()==Status.OK)
    ...{
        . . .
    }
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

  3. 在代碼行後添加註釋

若是多行代碼的每行都要添加註釋，則在每行代碼後添加該行的註釋，這將很容易理解。例如：

const MAX_ITEMS = 10 ; // maximum number of packets
const MASK = 0x1F ;     // mask bit TCP

  在分隔代碼和註釋時，有的開發者使用tab鍵，而另外一些則使用空格鍵。然而因爲tab鍵在各編輯器和IDE工具之間的表現不一致，所以最好的方法仍是使用空格鍵。

4. 不要侮辱讀者的智慧

避免如下顯而易見的註釋：寫這些無用的註釋會浪費你的時間，並將轉移讀者對該代碼細節的理解。

if (a == 5 )       // if a equals 5
    counter = 0 ; // set the counter to zero

  5. 禮貌點

避免粗魯的註釋，如：「注意，愚蠢的使用者纔會輸入一個負數」或「剛修復的這個問題出於最初的無能開發者之手」。這樣的註釋可以反映到它的做者是多麼的拙劣，你也永遠不知道誰將會閱讀這些註釋，多是：你的老闆，客戶，或者是你剛纔侮辱過的無能開發者。

6. 關注要點

不要寫過多的須要轉意且不易理解的註釋。避免ASCII藝術，搞笑，詩情畫意，hyperverbosity的註釋。簡而言之，保持註釋簡單直接。

7. 使用一致的註釋風格

一些人堅信註釋應該寫到能被非編程者理解的程度。而其餘的人則認爲註釋只要能被開發人員理解就好了。不管如何，Successful Strategies for Commenting Code已經規定和闡述了註釋的一致性和針對的讀者。就我的而言，我懷疑大部分非編程人員將會去閱讀代碼，所以註釋應該是針對其餘的開發者而言。

8. 使用特有的標籤

在一個團隊工做中工做時，爲了便於與其它程序員溝通，應該採用一致的標籤集進行註釋。例如，在不少團隊中用TODO標籤表示該代碼段還須要額外的工做。

int Estimate( int x, int y)
... {
    // TODO: implement the calculations
    return 0;
}

  註釋標籤切忌不要用於解釋代碼，它只是引發注意或傳遞信息。若是你使用這個技巧，記得追蹤並確認這些信息所表示的是什麼。

9. 在代碼時添加註釋

在寫代碼時就添加註釋，這時在你腦海裏的是清晰完整的思路。若是在代碼最後再添加一樣註釋，它將多花費你一倍的時間。而「我沒有時間寫註釋」，「我很忙」和「項目已經延期了」這都是不肯寫註釋而找的藉口。一些開發者以爲應該write comments before code，用於理清頭緒。例如：

public void ProcessOrder()
... {
    // Make sure the products are available
    // Check that the customer is valid
    // Send the order to the store
    // Generate bill
}

  10. 爲本身註釋代碼

當註釋代碼時，要考慮到不只未來維護你代碼的開發人員要看，並且你本身也可能要看。用Phil Haack大師的話來講就是：「一旦一行代碼顯示屏幕上，你也就成了這段代碼的維護者」。所以，對於咱們寫得好(差)的註釋而言，咱們將是第一個受益者(受害者)。