1. 對(duì)不同級(jí)別的代碼進(jìn)行注釋
對(duì)于不同級(jí)別的代碼塊，要使用統(tǒng)一的方法來(lái)進(jìn)行注釋。例如：
對(duì)于每一個(gè)類，需要包含一段簡(jiǎn)明扼要的描述，作者和上一次修改的時(shí)間
對(duì)于每一個(gè)方法，需要包含這個(gè)方法的用途，功能，參數(shù)以及返回結(jié)果
當(dāng)你在一個(gè)團(tuán)隊(duì)里面的時(shí)候，采用一套注釋的標(biāo)準(zhǔn)是非常重要的。當(dāng)然，使用一種大家都認(rèn)可的注釋約定和工具（例如C#的XML注釋和Java的Javadoc）在一定程度上能推動(dòng)這項(xiàng)任務(wù)。

2. 使用段落注釋
首先把代碼塊分解成多個(gè)“段落”，每一個(gè)段落都執(zhí)行單一的任務(wù)；然后在每一個(gè)“段落”開(kāi)始之前添加注釋，告訴閱讀代碼的人接下來(lái)的這段代碼是干什么用的
復(fù)制內(nèi)容到剪貼板
代碼:

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

3. 對(duì)齊注釋行
對(duì)于那些在行末寫(xiě)有注釋的代碼，應(yīng)該對(duì)齊注釋行來(lái)使得方便閱讀

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

有些開(kāi)發(fā)人員使用tab來(lái)對(duì)齊注釋，而另外一些人會(huì)用空格來(lái)對(duì)齊。由于tab在不同的編輯器和集成開(kāi)發(fā)環(huán)境中會(huì)有所不同，所以最佳的方法是使用空格來(lái)對(duì)齊注釋行。

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

要避免沒(méi)用的注釋，代碼:

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

這不單把時(shí)間浪費(fèi)在寫(xiě)沒(méi)用的注釋上面，同時(shí)也在分散讀者的注意力。

5. 要有禮貌
應(yīng)當(dāng)避免沒(méi)有禮貌的注釋，例如“要注意一些愚蠢的用戶會(huì)輸入一個(gè)負(fù)數(shù)”，或者“修正由菜鳥(niǎo)工程師寫(xiě)的愚蠢得可憐的代碼而導(dǎo)致的副作用”。這樣的注釋對(duì)于代碼的寫(xiě)注釋的人來(lái)說(shuō)并沒(méi)有任何好處，同時(shí)你永遠(yuǎn)都不會(huì)知道將來(lái)這些注釋會(huì)被誰(shuí)來(lái)閱讀，你的老板，一個(gè)客戶或者是剛才被你數(shù)落的愚蠢得可憐的工程師。

6. 直截了當(dāng)
不要在注釋里面寫(xiě)過(guò)多的廢話。避免在注釋里面賣弄ASCII藝術(shù)，寫(xiě)笑話，作詩(shī)和過(guò)于冗長(zhǎng)。簡(jiǎn)而言之就是保持注釋的簡(jiǎn)單和直接。

7. 使用統(tǒng)一的風(fēng)格
有些人覺(jué)得注釋?xiě)?yīng)該讓非程序員也能看懂。另外一些人覺(jué)得注釋需要面對(duì)的讀者只是程序員。無(wú)論如何，正如Successful Strategies for Commenting Code中所說(shuō)的，最重要的是注釋的風(fēng)格需要統(tǒng)一，并且總是面向相同的讀者。就自己而論，我懷疑非程序員是否會(huì)去讀代碼，所以我覺(jué)得注釋?xiě)?yīng)該面向程序員來(lái)寫(xiě)。

8. 在內(nèi)部使用特殊的標(biāo)簽
當(dāng)你在一個(gè)團(tuán)隊(duì)里工作的時(shí)候，采用一組一致的標(biāo)簽?zāi)軒椭煌某绦騿T溝通。例如，很多團(tuán)隊(duì)會(huì)采用“TODO”標(biāo)簽來(lái)表示一段尚未完成的代碼
復(fù)制內(nèi)容到剪貼板
代碼:

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

標(biāo)簽注釋并不會(huì)解釋代碼，它們尋求注意或者是傳遞信息。但是如果適當(dāng)?shù)厥褂眠@種技術(shù)，要記住跟進(jìn)這段代碼并且完成該標(biāo)簽傳遞的任務(wù)。

9. 在寫(xiě)代碼的同時(shí)添加注釋
當(dāng)你在寫(xiě)代碼而且記憶猶新的同時(shí)就添加注釋。如果等到項(xiàng)目后期才添加注釋，會(huì)讓你事倍功半。“我沒(méi)有時(shí)間寫(xiě)注釋”，“我的時(shí)間很緊迫”和“項(xiàng)目已經(jīng)延遲了”，這些都是不寫(xiě)注釋的常見(jiàn)借口。有些工程師覺(jué)最佳的解決方法是“注釋先行”。例如：
復(fù)制內(nèi)容到剪貼板
代碼:

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

10. 把自己想象為注釋的讀者（事實(shí)上就是如此）
當(dāng)你正在給代碼寫(xiě)注釋的時(shí)候，不僅僅為日后維護(hù)你的代碼的開(kāi)發(fā)者考慮，同時(shí)也設(shè)想一下如果自己就是注釋的讀者。Phil Haack曾經(jīng)說(shuō)過(guò)：
“一旦一行代碼被敲到文件中, 你就已經(jīng)要開(kāi)始維護(hù)那一行代碼了。”
所以，我們自己就是好（或者壞）注釋的第一個(gè)受益者（或者受害者）。

11. 更新代碼的時(shí)候要更新注釋

如果注釋沒(méi)有隨著代碼的修改而更新，那么這些注釋將是毫無(wú)意義的。代碼和注釋需要同步，否則注釋只會(huì)讓維護(hù)代碼的開(kāi)發(fā)者更加痛苦。需要特別注意的是，一些重構(gòu)的工具會(huì)自動(dòng)更新代碼，但是卻沒(méi)有自動(dòng)更新注釋，那么注釋就自然而然地過(guò)期作廢了。

12. 良好可讀性代碼是注釋的金科玉律
對(duì)于很多開(kāi)發(fā)者來(lái)說(shuō)，一個(gè)基本的原則就是：讓代碼自己描述自己。雖然有人懷疑這是由不喜歡寫(xiě)注釋的程序員所倡導(dǎo)的一場(chǎng)運(yùn)動(dòng)，但是無(wú)需解釋的代碼有很大的好處，這些代碼更加容易理解甚至讓注釋變得沒(méi)有必要。例如，在我的文章Fluid Interfaces中就給大家展示了什么是清晰的無(wú)需解釋的代碼。
復(fù)制內(nèi)容到剪貼板
代碼:

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

在這個(gè)例子里面，注釋就像是違反了第4條技巧那樣，變得毫無(wú)必要。要寫(xiě)出可讀性好的代碼，你需要使用適當(dāng)?shù)拿绞?#xff08;在經(jīng)典的Ottinger’s Rules中有闡述），保證恰當(dāng)?shù)目s進(jìn)，并且采用編碼風(fēng)格指導(dǎo)。如果代碼不遵守這條技巧，那么注釋看起來(lái)就好像是為自己不好的代碼的寫(xiě)道歉信一樣。

13. 跟你的同事分享這些技巧
雖然從第10條技巧中我們已經(jīng)知道了自己就是好注釋的得益者，但是這些技巧對(duì)于所有的開(kāi)發(fā)者來(lái)說(shuō)都是很有幫助的，尤其是整個(gè)團(tuán)隊(duì)都有相同共識(shí)的情況下。因此，大方地跟你的同事去分享這些技巧，讓我們寫(xiě)出更加容易理解和維護(hù)的代碼。

轉(zhuǎn)載于:https://blog.51cto.com/yangyoushan/1276580

總結(jié)

以上是生活随笔為你收集整理的十三个代码注释的小技巧的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

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