網頁設計公司必讀的文章 ( 114 ) 13個代碼註釋的小技巧

這篇文章是由Jose M. Aguilar在他卓越的博客中以西班牙語的形式首發，其後Timm Martin在獲得Aguilar先生的授權下，對該文章進行翻譯、修改，並且在DevTopics上發佈。

以下13個小技巧可以使得你的代碼在長時間內依然能夠保持容易理解和維護。

1. 對不同級別的代碼進行註釋

對於不同級別的代碼塊，要使用統一的方法來進行註釋。例如：

對於每一個類，需要包含一段簡明扼要的描述，作者和上一次修改的時間
對於每一個方法，需要包含這個方法的用途，功能，參數以及返回結果
當你在一個團隊裡面的時候，採用一套註釋的標準是非常重要的。當然，使用一種大家都認可的註釋約定和工具（例如C#的XML註釋和Java的Javadoc）在一定程度上能推動這項任務。

2. 使用段落註釋

首先把代碼塊分解成多個「段落」，每一個段落都執行單一的任務；然後在每一個「段落」開始之前添加註釋，告訴閱讀代碼的人接下來的這段代碼是幹什麼用的

// 檢查所有記錄都是正確的
foreach (Record record in records)
{
    if (rec.checkStatus()==Status.OK)
    {
        . . .
    }
}
// 現在開始進行處理
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .

3. 對齊註釋行

對於那些在行末寫有註釋的代碼，應該對齊註釋行來使得方便閱讀

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

有些開發人員使用tab來對齊註釋，而另外一些人會用空格來對齊。由於tab在不同的編輯器和集成開發環境中會有所不同，所以最佳的方法是使用空格來對齊註釋行。

4. 不要侮辱閱讀者的智慧

要避免沒用的註釋，例如

if (a == 5)        //如果a等於5
    counter = 0    //把counte設為0

這不單把時間浪費在寫沒用的註釋上面，同時也在分散讀者的注意力。

5. 要有禮貌

應當避免沒有禮貌的註釋，例如「要注意一些愚蠢的用戶會輸入一個負數」，或者「修正由菜鳥工程師寫的愚蠢得可憐的代碼而導致的副作用」。這樣的註釋對於代碼的寫註釋的人來說並沒有任何好處，同時你永遠都不會知道將來這些註釋會被誰來閱讀，你的老闆，一個客戶或者是剛才被你數落的愚蠢得可憐的工程師。

6. 直截了當

不要在註釋裡面寫過多的廢話。避免在註釋裡面賣弄ASCII藝術，寫笑話，作詩和過於冗長。簡而言之就是保持註釋的簡單和直接。

7. 使用統一的風格

有些人覺得註釋應該讓非程序員也能看懂。另外一些人覺得註釋需要面對的讀者只是程序員。無論如何，正如Successful Strategies for Commenting Code中所說的，最重要的是註釋的風格需要統一，並且總是面向相同的讀者。就自己而論，我懷疑非程序員是否會去讀代碼，所以我覺得註釋應該面向程序員來寫。

8. 在內部使用特殊的標籤

當你在一個團隊裡工作的時候，採用一組一致的標籤能幫助不同的程序員溝通。例如，很多團隊會採用「TODO」標籤來表示一段尚未完成的代碼

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

標籤註釋並不會解釋代碼，它們尋求注意或者是傳遞信息。但是如果適當地使用這種技術，要記住跟進這段代碼並且完成該標籤傳遞的任務。

9. 在寫代碼的同時添加註釋

當你在寫代碼而且記憶猶新的同時就添加註釋。如果等到項目後期才添加註釋，會讓你事倍功半。「我沒有時間寫註釋」，「我的時間很緊迫」和「項目已經延遲了」，這些都是不寫註釋的常見借口。有些工程師覺最佳的解決方法是「註釋先行」。例如：

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曾經說過：

「一旦一行代碼被敲到文件中, 你就已經要開始維護那一行代碼了。」

所以，我們自己就是好（或者壞）註釋的第一個受益者（或者受害者）。

11. 更新代碼的時候要更新註釋

如果註釋沒有隨著代碼的修改而更新，那麼這些註釋將是毫無意義的。代碼和註釋需要同步，否則註釋只會讓維護代碼的開發者更加痛苦。需要特別注意的是，一些重構的工具會自動更新代碼，但是卻沒有自動更新註釋，那麼註釋就自然而然地過期作廢了。

12. 良好可讀性代碼是註釋的金科玉律

對於很多開發者來說，一個基本的原則就是：讓代碼自己描述自己。雖然有人懷疑這是由不喜歡寫註釋的程序員所倡導的一場運動，但是無需解釋的代碼有很大的好處，這些代碼更加容易理解甚至讓註釋變得沒有必要。例如，在我的文章Fluid Interfaces中就給大家展示了什麼是清晰的無需解釋的代碼。

Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( 「Result: {0}」, calc.Get() );

在這個例子裡面，註釋就像是違反了第4條技巧那樣，變得毫無必要。要寫出可讀性好的代碼，你需要使用適當的命名方式（在經典的Ottinger』s Rules中有闡述），保證恰當的縮進，並且採用編碼風格指導。如果代碼不遵守這條技巧，那麼註釋看起來就好像是為自己不好的代碼的寫道歉信一樣。

13. 跟你的同事分享這些技巧

雖然從第10條技巧中我們已經知道了自己就是好註釋的得益者，但是這些技巧對於所有的開發者來說都是很有幫助的，尤其是整個團隊都有相同共識的情況下。因此，大方地跟你的同事去分享這些技巧，讓我們寫出更加容易理解和維護的代碼。