// 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

在分隔代碼和注釋時，有的開發(fā)者使用tab鍵，而另一些則使用空格鍵。然而由于tab鍵在各編輯器和IDE工具之間的表現(xiàn)不一致，因此最好的方法還是使用空格鍵。

4. 不要侮辱讀者的智慧

避免以下顯而易見的注釋：寫這些無用的注釋會浪費(fèi)你的時間，并將轉(zhuǎn)移讀者對該代碼細(xì)節(jié)的理解。

if (a == 5)   // if a equals 5
  counter = 0; // set the counter to zero

5. 禮貌點(diǎn)

避免粗魯?shù)淖⑨?，如：“注意，愚蠢的使用者才會輸入一個負(fù)數(shù)”或“剛修復(fù)的這個問題出于最初的無能開發(fā)者之手”。這樣的注釋能夠反映到它的作者是多么的拙劣，你也永遠(yuǎn)不知道誰將會閱讀這些注釋，可能是：你的老板，客戶，或者是你剛才侮辱過的無能開發(fā)者。

6. 關(guān)注要點(diǎn)

不要寫過多的需要轉(zhuǎn)意且不易理解的注釋。避免ASCII藝術(shù)，搞笑，詩情畫意，hyperverbosity的注釋。簡而言之，保持注釋簡單直接。

7. 使用一致的注釋風(fēng)格

一些人堅信注釋應(yīng)該寫到能被非編程者理解的程度。而其他的人則認(rèn)為注釋只要能被開發(fā)人員理解就行了。無論如何，Successful Strategies for Commenting Code已經(jīng)規(guī)定和闡述了注釋的一致性和針對的讀者。就個人而言，我懷疑大部分非編程人員將會去閱讀代碼，因此注釋應(yīng)該是針對其他的開發(fā)者而言。

8. 使用特有的標(biāo)簽

在一個團(tuán)隊工作中工作時，為了便于與其它程序員溝通，應(yīng)該采用一致的標(biāo)簽集進(jìn)行注釋。例如，在很多團(tuán)隊中用TODO標(biāo)簽表示該代碼段還需要額外的工作。

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

注釋標(biāo)簽切忌不要用于解釋代碼，它只是引起注意或傳遞信息。如果你使用這個技巧，記得追蹤并確認(rèn)這些信息所表示的是什么。

9. 在代碼時添加注釋

在寫代碼時就添加注釋，這時在你腦海里的是清晰完整的思路。如果在代碼最后再添加同樣注釋，它將多花費(fèi)你一倍的時間。而“我沒有時間寫注釋”，“我很忙”和“項目已經(jīng)延期了”這都是不愿寫注釋而找的借口。一些開發(fā)者覺得應(yīng)該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. 為自己注釋代碼

當(dāng)注釋代碼時，要考慮到不僅將來維護(hù)你代碼的開發(fā)人員要看，而且你自己也可能要看。用Phil Haack大師的話來說就是：“一旦一行代碼顯示屏幕上，你也就成了這段代碼的維護(hù)者”。因此，對于我們寫得好(差)的注釋而言，我們將是第一個受益者(受害者)。

您可能感興趣的文章: