本文講述了提高代碼可讀性的十大注釋技巧。分享給大家供大家參考，具體如下：
很多程序員在寫(xiě)代碼的時(shí)候往往都不注意代碼的可讀性，讓別人在閱讀代碼時(shí)花費(fèi)更多的時(shí)間。其實(shí)，只要程序員在寫(xiě)代碼的時(shí)候，注意為代碼加注釋?zhuān)⒁院侠淼母袷綖榇a加注釋?zhuān)@樣就方便別人查看代碼，也方便自己以后查看了。下面分享十個(gè)加注釋的技巧：
1. 逐層注釋
為每個(gè)代碼塊添加注釋?zhuān)⒃诿恳粚邮褂媒y(tǒng)一的注釋方法和風(fēng)格。例如：
針對(duì)每個(gè)類(lèi)：包括摘要信息、作者信息、以及最近修改日期等；
針對(duì)每個(gè)方法：包括用途、功能、參數(shù)和返回值等。
在團(tuán)隊(duì)工作中，采用標(biāo)準(zhǔn)化的注釋尤為重要。當(dāng)然，使用注釋規(guī)范和工具(例如C#里的XML，Java里的Javadoc)可以更好的推動(dòng)注釋工作完成得更好。
2. 使用分段注釋
如果有多個(gè)代碼塊，而每個(gè)代碼塊完成一個(gè)單一任務(wù)，則在每個(gè)代碼塊前添加一個(gè)注釋來(lái)向讀者說(shuō)明這段代碼的功能。例子如下：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
// Check that all data records// are correctforeach (Record record in records){ if (rec.checkStatus()==Status.OK) { . . . }}// Now we begin to perform// transactionsContext ctx = new ApplicationContext();ctx.BeginTransaction();. . . |
3. 在代碼行后添加注釋
如果多行代碼的每行都要添加注釋?zhuān)瑒t在每行代碼后添加該行的注釋?zhuān)@將很容易理解。例如：
|
1
2
|
const MAX_ITEMS = 10; // maximum number of packetsconst MASK = 0x1F; // mask bit TCP |
在分隔代碼和注釋時(shí)，有的開(kāi)發(fā)者使用tab鍵，而另一些則使用空格鍵。然而由于tab鍵在各編輯器和IDE工具之間的表現(xiàn)不一致，因此最好的方法還是使用空格鍵。
4. 不要侮辱讀者的智慧
避免以下顯而易見(jiàn)的注釋?zhuān)簩?xiě)這些無(wú)用的注釋會(huì)浪費(fèi)你的時(shí)間，并將轉(zhuǎn)移讀者對(duì)該代碼細(xì)節(jié)的理解。
|
1
2
|
if (a == 5) // if a equals 5 counter = 0; // set the counter to zero |
5. 禮貌點(diǎn)
避免粗魯?shù)淖⑨專(zhuān)纾?ldquo;注意，愚蠢的使用者才會(huì)輸入一個(gè)負(fù)數(shù)”或“剛修復(fù)的這個(gè)問(wèn)題出于最初的無(wú)能開(kāi)發(fā)者之手”。這樣的注釋能夠反映到它的作者是多么的拙劣，你也永遠(yuǎn)不知道誰(shuí)將會(huì)閱讀這些注釋?zhuān)赡苁牵耗愕睦习澹蛻簦蛘呤悄銊偛盼耆柽^(guò)的無(wú)能開(kāi)發(fā)者。
6. 關(guān)注要點(diǎn)
不要寫(xiě)過(guò)多的需要轉(zhuǎn)意且不易理解的注釋。避免ASCII藝術(shù)，搞笑，詩(shī)情畫(huà)意，hyperverbosity的注釋。簡(jiǎn)而言之，保持注釋簡(jiǎn)單直接。
7. 使用一致的注釋風(fēng)格
一些人堅(jiān)信注釋?xiě)?yīng)該寫(xiě)到能被非編程者理解的程度。而其他的人則認(rèn)為注釋只要能被開(kāi)發(fā)人員理解就行了。無(wú)論如何，Successful Strategies for Commenting Code已經(jīng)規(guī)定和闡述了注釋的一致性和針對(duì)的讀者。就個(gè)人而言，我懷疑大部分非編程人員將會(huì)去閱讀代碼，因此注釋?xiě)?yīng)該是針對(duì)其他的開(kāi)發(fā)者而言。
8. 使用特有的標(biāo)簽
在一個(gè)團(tuán)隊(duì)工作中工作時(shí)，為了便于與其它程序員溝通，應(yīng)該采用一致的標(biāo)簽集進(jìn)行注釋。例如，在很多團(tuán)隊(duì)中用TODO標(biāo)簽表示該代碼段還需要額外的工作。
|
1
2
3
4
5
|
int Estimate(int x, int y){ // TODO: implement the calculations return 0;} |
注釋標(biāo)簽切忌不要用于解釋代碼，它只是引起注意或傳遞信息。如果你使用這個(gè)技巧，記得追蹤并確認(rèn)這些信息所表示的是什么。
9. 在代碼時(shí)添加注釋
在寫(xiě)代碼時(shí)就添加注釋?zhuān)@時(shí)在你腦海里的是清晰完整的思路。如果在代碼最后再添加同樣注釋?zhuān)鼘⒍嗷ㄙM(fèi)你一倍的時(shí)間。而“我沒(méi)有時(shí)間寫(xiě)注釋”，“我很忙”和“項(xiàng)目已經(jīng)延期了”這都是不愿寫(xiě)注釋而找的借口。一些開(kāi)發(fā)者覺(jué)得應(yīng)該write comments before code，用于理清頭緒。例如：
|
1
2
3
4
5
6
7
|
public void ProcessOrder(){ // Make sure the products are available // Check that the customer is valid // Send the order to the store // Generate bill} |
10. 為自己注釋代碼
當(dāng)注釋代碼時(shí)，要考慮到不僅將來(lái)維護(hù)你代碼的開(kāi)發(fā)人員要看，而且你自己也可能要看。用Phil Haack大師的話來(lái)說(shuō)就是：“一旦一行代碼顯示屏幕上，你也就成了這段代碼的維護(hù)者”。因此，對(duì)于我們寫(xiě)得好(差)的注釋而言，我們將是第一個(gè)受益者(受害者)。
