(翻譯) 註解程式碼的13個建議 (C/C++)

Abstract
本文例舉了我們在註解程式碼時的13個小技巧，這讓我們的代碼更易讀懂,更易維護。

Introduction
原文出處：http://www.devtopics.com/13-tips-to-comment-your-code/
簡中翻譯：http://www.cnblogs.com/nicholasun/archive/2008/04/26/1171557.html

本文採用簡中翻譯為藍本，潤飾成繁中翻譯。

1.Comment each level
對每一層級採用統一的方式注釋每個程式碼區塊，例如：
    *為每個class，包含簡短的描述，如作者和最後修改日期。
    *為每個member function(method)，包含其目的，功能，參數，傳回值。
團隊程式設計時，採用標準的註解是很重要的。當然，採用代碼協定和工具（真 OO無雙譯註：如C++的doxygen，c#的XMLDoc和java中的Javadoc）幫助這項工作也是可接受的，甚至強烈推薦。

2.Use paragraph comments
將代碼塊分成多個片段，每個片段執行一個簡單的任務，然後在每個片段前添加註解，引導讀者即將發生什麼。

// 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.Align comments in consecutive lines
對於多行且每行後都緊跟著註解的情況，我們應該對這些註解做排版，使它們更易讀懂。(真 OO無雙譯註：如每個註解的起始位置相同)。

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

一些開發人員用Tab來排列注釋，其他的則用空格。最佳途徑還是用空格，因為在各種編輯器和IDE中，tab鍵的設定差異頗大。(真 OO無雙譯註：若你需將code貼到email或web上時，儘管你原來的code排的漂漂亮亮，但對方因為Tab設定與你不同，看到的將是亂七八糟的code，但空格四海皆準，你的排版不會跑掉。)

4.Don’t insult the reader’s intelligence
避免多餘的註解，比如：

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

這既浪費時間寫不必要的註解，又使讀者分心，因為這些細節讀者很容易從你的代碼中推斷出來。

5.Be polite
避免粗魯的註解，比如“Notice the stupid user has entered a negative number,”或“This fixes the side effect produced by the pathetically inept implementation of the initial developer”。此類註解很難在他們的程式碼中得到好的效果，並且你甚至不知道以後誰會讀這種註解，你的上司，客戶或可憐的愚蠢的新手。

6.Get to the point
不要寫無關你要傳達意思的註解。避免笑話，詩歌和贅言。簡而言之，保持註解簡潔，直接。

7.Use a consistent style
一些人認為註解應該寫的讓非開發人員也能明白，其他人則認為只對開發人員即可。無論如何，作為成功的程式碼註解策略，應該是一致的以及總是針對相同的讀者。個人意見，我甚至懷疑很多非開發人員是否會讀程式碼，所以注釋應針對開發人員。

8.Use special tags for internal use
團隊開發時，採用一致的一套標籤作為開發人員間的溝通。比如，很多團隊使用“TODO:”標籤來指出需要附加編寫的程式碼片段：

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

9.Comment code while writing it
在編寫程式碼時添加註解，此時它們在你腦中還是清晰的。如果你直到最後才來添加，將事倍功半。“I have no time to comment“(我沒時間寫註解)，”I’m in a hurry”(我在趕時間)和“the project is delayed”(專案已經延誤了)都是些藉口。一些開發人員認為你應該在編寫代碼前寫註解作為一種籌畫最終方案的途徑。例如：

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

10.Write comments as if they were for you(in fact,they are)
註解程式碼時，不僅僅要考慮其他開發人員以後可能會維護你的代碼，也要考慮你自己。偉大的Phil Haack曾說過："As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code."(只要在螢幕上有程式碼，你就是在那段程式碼的維護模式)，結果是，我們自己將是優良（笨拙）注釋的第一個受益（害）者。

11.Update comments when you update the code
如果註解沒有隨著程式碼更新，那樣的註解不能保證正確。程式碼和註解必須同步修改，否則你的註解將使維護你程式碼的開發人員的工作很難做。特別要注意重構工具自動的更新了你的程式碼而沒有改變你的註解的情況，這也將導致同樣的結果。

12.The golden role of comment:readable code
開發人員的基本功之一：讓你的程式碼為自己說話。儘管一些不喜歡寫註解的人懷疑這是開發人員們瞎編亂造的，不過事實是乾淨清楚的程式碼對於編寫更易懂的程式碼，甚至使註解變的不必要有很好的幫助。例如，在我的Fluid Interfaces文章中展示了乾淨清楚的程式碼可能是這樣的：

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

在這個例子裡，註解是不需要的，而且那樣做可能會與第4條相違背。為了寫出更易讀的程式碼，你可能要考慮使用合適的命名方式（Stringer’s Rules）,確保正確的縮排和採用程式碼樣式指南。不遵守這條提示的結果可能是註解看起來像似對糟糕的程式碼道歉。

13.Share these tips with your colleagues
儘管我們在第10條中指出我們自己是怎樣立即從優良的註解受益的，但是這些條款對所有開發人員都有用，尤其是團隊開發。因此，請將這些註解條款與你的同事分享，一起寫易懂和易維護的代碼。