(轉)寫好程序注釋的十三條建議


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

 


免責聲明!

本站轉載的文章為個人學習借鑒使用,本站對版權不負任何法律責任。如果侵犯了您的隱私權益,請聯系本站郵箱yoyou2525@163.com刪除。



 
粵ICP備18138465號   © 2018-2025 CODEPRJ.COM