註釋程式碼的13技巧

本文發表在作者José M. Aguilar的部落格Variable Not Found，後來由Timm Martin翻譯成英文發表在DevTopics上。

以下是如何註釋程式碼的13tips，它們會在日後幫助你更容易理解和維護程式碼。

1. Comment each level（每個級別的註釋有統一的風格）

註釋每一個程式碼塊，並且在各個級別的程式碼塊上，要使用統一的註釋方法。例如：

對於類，應包含簡單的描述、作者以及最近的更改日期 
對於方法，應包含目的的描述、功能、引數以及返回值

使用統一的註釋規則對於一個團隊是非常重要的。當然，更加推薦使用註釋的約定和工具（例如，C#的XML或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（對齊註釋行）

對於擁有字尾式註釋的多行程式碼，排版註釋程式碼，使各行註釋對齊到同一列。

const MAX_ITEMS = 10; // maximum number of packets

const MASK = 0x1F; // mask bit TCP

一些開發人員使用tab來對齊註釋，有些則使用空格。但是由於tab在不同的編輯器或者IDE上會有所不同，最好還是使用空格。

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（要有禮貌）

不要寫不禮貌的註釋程式碼，例如"注意，愚蠢的使用者輸入了一個負數"，或者"修正由於最初的開發者的可憐且愚蠢的編碼所造成的副作用"。這樣的註釋冒犯了作者，而且你並不知道誰會在將來讀到這段註釋--你老闆、客戶或者是你在註釋中冒犯的那個可憐且愚蠢的開發人員。

6. Get to the point（簡明扼要）

不要在註釋中寫的過多，不要寫玩笑、詩和冗長的話。總之，註釋需要簡單直接。

7. Use a consistent style（風格一致）

一些人認為註釋應該能讓非程式設計師也能看懂，但是也有些人認為註釋僅僅是指導程式設計師的。不管怎麼說，像《Successful Strategies for Commenting Code》中所說，真正重要的是註釋始終面向同一個讀者，在這點上，應該保持一致。個人認為，我很懷疑會有非程式人員閱讀程式碼，所以應該把閱讀註釋的物件定位為開發人員。

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（寫程式碼的同時，完成註釋）

寫程式碼的同時新增註釋，因為此時你的思路最為清晰。如果你把註釋的任務留到最後，那麼你相當於經歷了兩次編碼。"我沒有時間註釋""我太忙了""專案耽誤了"這些往往是不寫註釋的理由。所以，程式設計師們認為，最理想的解決方法是‘寫程式碼前先寫註釋'。例如：

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（更新程式碼時，記得更新註釋）

如果不能隨著程式碼的更新而更新註釋，那麼即使再準確的註釋也毫無意義。程式碼和註釋必須同步，否則這些註釋對於維護你程式碼的程式人員來說簡直是折磨。在使用refactoring工具自動更新程式碼時，應尤其注意，它們會自動更新程式碼而不會改變註釋，這些註釋自然就過期了。

 

12. The golden rule of comments: 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() );

在本例中，註釋是沒必要的，並且會違背tip#4 。為了使程式碼更加可讀，應該考慮使用適當的名字（像在經典的《Ottinger's Rules》描述的），確保正確的縮排和程式碼風格欄線（程式碼風格欄線是類似於#region #endregion這類的東西吧？）。如果這一點做的不好，直接後果是，你的註釋看起來就像是在為晦澀難懂的程式碼而道歉。

13. Share these tips with your colleagues（與你的同事share這些tips）

儘管tip#10中曾說過良好的註釋會是自己從中收益，但是這些tips會使所有開發人員收益，尤其是在團隊合作的環境中。因此大方的與同事分享這些註釋的技巧，讓我們都能寫出易懂而且好維護的程式碼。