如何添加代碼注釋？
這個我一直沒有搞懂。自己隨便涂鴉，也懶得加注釋。但是真正參加項目，有時也會找理由不添注釋。看了一些書，參加一些培訓，有的人說，加注釋好，有人說加注釋不好。好有好的地方，壞也有壞的味道。對于我這個初來乍到之人來說，反而倒是非常迷惑。
最近看到一篇文章“添加代碼注釋13個技巧”，也解除了心中的部分疑團。貼在這里與大家分享，也備以后參考。
鏈接：
http://sunxinhe.yo2.cn/articles/%E3%80%90%E8%BD%AC%E3%80%91%E6%B7%BB%E5%8A%A0%E4%BB%A3%E7%A0%81%E6%B3%A8%E9%87%8A13%E4%B8%AA%E6%8A%80%E5%B7%A7.html

添加代碼注釋13個技巧

作者：José M. Aguilar（西班牙語）
英文譯者：Timm Martin
中文譯者：numenzq

下面的13個技巧向你展示如何添加代碼注釋，這些技巧都很容易理解和記憶。

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大師的話來說就是：“一旦一行代碼顯示屏幕上，你也就成了這段代碼的維護者”。因此，對于我們寫得好（差）的注釋而言，我們將是第一個受益者（受害者）。

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里講解得相當好），確保正確的縮進，并且采用coding style guides，違背這個技巧可能的結果就像是注釋在為不好的代碼apologize。

13. 與同事分享技巧
雖然技巧10已經向我們表明了我們是如何從好的注釋中直接受益，這些技巧將讓所有開發者受益，特別是團隊中一起工作的同事。因此，為了編寫出更容易理解和維護的代碼，嘗試自由的和你的同事分享這些注釋技巧。

好東西拿出來一起分享