下面的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; //?數據包的最大數量?
const MASK = 0x1F;??? //?TCP標志位

有些程序遠使用制表符來進行對齊，有些則使用空格。建議使用空格來對齊，因為不同的代碼編輯器對制表符的處理會不一樣。

4、不要侮辱讀者的智商

不要用這樣的注釋：

if (a == 5)????? // 如果a等于5
??? counter = 0; // 就將counter的值賦為0

這樣做只會浪費你的時間，而且讀者的注意力會被從代碼中轉移。

5、注意禮貌

避免使用無禮的注釋，如：注意有些蠢蛋會輸入一個負數；這修復了程序最初版本遇到的問題，那個無個救藥的笨蛋。這樣的注釋會反映作者的素質，而且你不知道將來誰會讀到你的程序：你的老板、顧客，或者是你剛才辱罵過的那個程序員。

6、講重點

不要在寫冗余的注釋，也不要用所謂的字符藝術、玩笑、小詩等。總之要保持注釋的簡單和直接。

7、堅持統一風格

有些人認為代碼注釋應該簡單到讓不會編程的人也能看懂，另一些人則認為代碼注釋只要讓程序員看懂就可以了。不管怎樣，正如《撰寫代碼注釋的成功策略?》中所提到的，代碼注釋的風格應該是固定的，是為同一個觀眾準備的。而且我個人認為不太會有非程序員來閱讀代碼，所以代碼注釋應該只是針對其他程序員的。

8、使用內部統一規定的標簽

在進行團隊開發時，可以在注釋中使用一些特殊的標簽。比如在一些團隊中使用“TODO:“標簽來表示這里還需要完成其他的一些任務。

int Estimate(int x, int y)
{
??? // TODO: 實現這項計算
??? return 0;
}

這里所使用的標簽注釋并不是用來解釋代碼，而是引起讀者注意并傳遞一些信息。如果你的團隊確實在使用這類注釋，就要保證會依此進行作業。

9、邊寫代碼邊注釋

在寫代碼的時候，乘腦中記憶還清晰，及時寫上注釋。如果你想在程序編寫完之后再添加注釋，也許就會花費你兩倍的時間。“我沒有時間添加注釋”、“我很忙”、“這個項目已經有所拖延了”都將會是你的借口。有些程序員認為你應該在編寫代碼之前就寫好注釋?，以為你的最終方案作出計劃。如：

??? public void ProcessOrder()?
??? {
??????? // 保證這些產品是可以購買得到的
??????? // 檢查用戶時候合法
??????? // 向商店發出訂單
??????? // 生成賬單
??? }

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() );

在這個例子中，代碼不需要注釋，否則會違反本文的第四條貼士。要寫出可讀的代碼，你應該考慮使用恰當的名稱（在Ottinger's Rules?中有所敘述），確保標識正確，并根據代碼規范?來撰寫。如果沒有遵循此條建議，注釋可能會被看作是代碼的一種“道歉”。

13、和你的同事分享這些貼士

雖然第10條貼士說我們自己將是代碼注釋的第一個受益者，但如果把這些貼士分享給你的同事，尤其是在同一個團隊中工作的同事，你就會發現你們寫出的代碼注釋會更為易懂和易于維護。

總結

以上是生活随笔為你收集整理的13个代码注释的小贴士的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。