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會使所有開發人員收益,尤其是在團隊合作的環境中。因此大方的與同事分享這些注釋的技巧,讓我們都能寫出易懂而且好維護的代碼。