Tips to Comment Your Code

 

Tips to Comment Your Code
（原文地址：http://www.devtopics.com/13-tips-to-comment-your-code/）

    這篇文章是西班牙的jose M.Aguilar在他優秀的blog variable not found裡發表的，得到他的允許後，Timm martin翻譯修改後重新在這裡發布。

下面13條技巧是關於如何如何注釋你的代碼，使得它即使隨著時間的流逝仍易於理解和維護。

1.注釋每一級
注釋每一個代碼塊，對於每一層級的代碼使用統一的注釋方法.比如：
*針對每個類，注釋包含一個簡單的描述，作者和最近修改日期。

*針對每個方法，包括一個它目的的描述，功能，參數和結果.
當在一個團隊裡採用一個注釋標準是重要的。當然，為了有利於注釋任務使用注釋約定和工具（例如在C#裡用XML，JAVA裡使用JAVADOC）是可接受的。

2.使用段落注釋。
     將代碼塊多個程式碼片段，每個程式碼片段完成一個簡單的任務，然後在每個代碼塊開始處添加備忘告知讀者它將要做什麼。
// 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
 一些開發人員使用tab鍵來排列注釋，但是其他人使用空格。tab會有不方便的地方，在編輯器和IED的切換中tab的效果可能會改變,最好的方式還是使用Space.(這點我不贊成，還是用TAB好，有IDE的情況下，沒人會用編輯器吧^_^ 不過如果有耐心使用SPACE使得效果像TAB一樣那最好)

4.不要侮辱讀者的智商
   避免顯而易見的注釋，像下面這樣：

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

 這浪費你的時間寫不需要的注釋，並且使用可以輕易從代碼推斷出來的細節來使讀者困惑。

 

5.文雅的注釋

   避免粗魯的注釋，像這樣，“注意愚蠢的使用者已經輸入一個負數” 或者 “這裡修補了最初可憐不稱職的開發人員實現的產品的側面效果”。對他們的作者這樣的注釋不會好的反應，並且你也不會知道將來誰可能讀到這些注釋，也許是你的老闆，客戶，或者剛剛被你侮辱的那位可憐的不稱職的開發人員。（誰會這麼無聊^_^）

6．在注釋列寫多餘你需要傳達的意思文字。避免ASCII字元，玩笑，詩和太緊湊（hyperverbosity） .簡短，保持注釋的簡單和直接。

7. 使用一致的風格

  一些人相信注釋應該寫到可以讓非程式員明白的程度。另外一些人認為注釋僅僅指導開發人員。在任何事件中，如文章Successful Strategies for Commenting Code裡說明的，問題的實質是注釋的組成和面對的是不是總是同樣的讀者。就我而言，我不懷疑會有很多非開發人員會讀到代碼，因為注釋還應該面向另外的開發人員。

8. 針對內部使用者使用專門的標記

 當作為一個團隊進行編碼工作時，應該採用一套標記在程式員中間交流。例如，許多團隊使用一個”TODO:”標記來指出需要附加工作的代碼部分：

int Estimate(int x, int y)
{
    // TODO: implement the calculations
    return 0;
}
標記注釋不是解釋代碼,而是提出需要注意或者表達一個資訊。但是如果你使用這個方法，記住要弄清楚實際做的時候需要什麼資訊。

 

9.當你寫代碼的時候同時注釋它。

   當你寫代碼的時候同時注釋它，這樣它在你的記憶力是新的。如果你直到最後才全部去注釋，你將花費兩倍長的時間。“我沒有時間去注釋”，“我很忙”或者“項目被延時了”這些都只不過是避免給你代碼寫文檔的借口。有些開發人員認為在寫代碼之前，應該先寫注釋，作為計劃你最終的解決方案的一個方法。比如：

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

 

10.如同他們是本該做的一樣的寫注釋（事實上，他們的確是）
當注釋代碼時，不僅要考慮將來那些需要維護你的代碼的開發人員，還需要為你自己考慮。在 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. 當你更新代碼時更新注釋。
 如果注釋沒有跟隨代碼改變，There is no point in commenting correctly on code（慚愧，不明白它的意思……）。代碼和注釋必須同步改變，否則對於將要維護的代碼的開發人員注釋將變成更加困難。特別注意重構工具，它們會更新你的代碼但是注釋卻沒有改變!

12.注釋的黃金準則：可讀性的代碼
     對於大多數開發人員的基本準則之一：讓你的代碼能說明自己。儘管有些人猜想這個準則是由那些不願意寫注釋的開發人員造成的,但是自解釋的代碼對編寫更容易理解代碼的確大有協助。比如，在我的文章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條。為了讓代碼更有可讀性，你可以考慮使用特定的名字（比如經典的文章Ottinger's Rules裡的描述）,保證正確的縮排，並且要有代碼風格。對於糟糕的代碼，失敗的遵守這個規則可能導致在apologize看到的注釋。

13.跟你的同事分享這些技巧。
第10條技巧說明我們怎樣從好的注釋裡得到好處，這些技巧對於所有開發人員都是有益的，特別在團隊裡一起工作的。因此，為了能編寫容易明白和維護代碼跟你的同事分享這些注釋技巧吧。

14. The code should explain how.
The comments should explain why. （回複在看到的，我覺得還不錯。）