下面的13條小貼士可以幫助你寫出更規(guī)范、更容易維護(hù)的代碼注釋。

1、逐層注釋

使用統(tǒng)一格式對每一個語句塊進(jìn)行注釋，如：

• 類：簡單描述、作者、最后修改時間等
• 方法：關(guān)于該方法的目的、函數(shù)、參數(shù)、返回值的描述

在團(tuán)隊工作中，使用統(tǒng)一的注釋規(guī)范顯得尤為重要。當(dāng)然，也推薦使用一些專門用來添加代碼注釋的工具，如C#中的XML、Java中的Javadoc等。

2、使用段落型注釋

將代碼分割成能完成獨(dú)立任務(wù)的段落，并在其前后添加注釋，告訴讀者程序?qū)⒁鍪裁础?/p>

// 檢查所有的記錄是否正確
foreach (Record record in records)?
{
????if (rec.checkStatus()==Status.OK)
????{?
????????. . .?
????}?
}?
// 現(xiàn)在開始進(jìn)行事務(wù)處理
Context ctx = new ApplicationContext();?
ctx.BeginTransaction();
. . .

3、對齊連續(xù)的行注釋

若對多行添加行末注釋，應(yīng)將注釋進(jìn)行對齊，以便于閱讀。

const MAX_ITEMS = 10; //?數(shù)據(jù)包的最大數(shù)量?
const MASK = 0x1F;??? //?TCP標(biāo)志位

有些程序遠(yuǎn)使用制表符來進(jìn)行對齊，有些則使用空格。建議使用空格來對齊，因?yàn)椴煌拇a編輯器對制表符的處理會不一樣。

4、不要侮辱讀者的智商

不要用這樣的注釋：

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

這樣做只會浪費(fèi)你的時間，而且讀者的注意力會被從代碼中轉(zhuǎn)移。

5、注意禮貌

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

6、講重點(diǎn)

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

7、堅持統(tǒng)一風(fēng)格

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

8、使用內(nèi)部統(tǒng)一規(guī)定的標(biāo)簽

在進(jìn)行團(tuán)隊開發(fā)時，可以在注釋中使用一些特殊的標(biāo)簽。比如在一些團(tuán)隊中使用“TODO:“標(biāo)簽來表示這里還需要完成其他的一些任務(wù)。

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

這里所使用的標(biāo)簽注釋并不是用來解釋代碼，而是引起讀者注意并傳遞一些信息。如果你的團(tuán)隊確實(shí)在使用這類注釋，就要保證會依此進(jìn)行作業(yè)。

9、邊寫代碼邊注釋

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

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

10、就當(dāng)是為自己寫注釋（事實(shí)上的確是讓你自己看的）

在添加代碼注釋時，要想到這些注釋不僅是為將來維護(hù)代碼的程序員而寫，也是為你自己而寫。用偉大的Phil Haack?的話來說：“當(dāng)一行代碼寫好并出現(xiàn)在屏幕上時，你就變成了一名維護(hù)人員。”所以，我們自己將會成為代碼注釋的第一個受益人或受害者。

11、更新代碼時同時更新注釋

如果注釋不隨著代碼的改變而修改，那在準(zhǔn)備的注釋也是沒有用的。代碼和注釋應(yīng)該始終保持同步，否則這些文不對題的注視將使維護(hù)人員摸不著頭腦。對于那些自動添加注釋的工具要格外注意，不要讓它忽略更新注釋。

12、黃金準(zhǔn)則：寫可讀的代碼

有一條基本準(zhǔn)備叫“讓代碼解釋它自己”。雖然有人認(rèn)為這個倡議是由一個懶得寫注釋的程序提出的，但不可否認(rèn)的是一條可以自我解釋的代碼可以讓其變得更為易懂，并讓注釋顯得不那么重要。如，在我的Fluid Interfaces?文章中有一些可以自我解釋的代碼的例子：

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

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

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

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

總結(jié)

以上是生活随笔為你收集整理的13条注释 tips的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。