程序代碼注釋的規范與建議

你的代碼注釋到位了嗎?
服務器君一共花費了168.512 ms進行了6次數據庫查詢,努力地為您提供了這個頁面。
試試閱讀模式?希望聽取您的建議
  1. Comment each level
  2. 對每一級用統一的方法注釋每個代碼塊,例如:

    • 為每個類,包含簡短的描述,作者和最后修改日期
    • 為每個方法,包含其目的,功能,參數,返回值

    團隊編程時,采用標準的注釋是很重要的。當然,采用代碼協定和工具(比如c#中的XML和java中的Javadoc)幫助這項工作也是可接受的,甚至更可取。

  3. Use paragraph comments
  4. 將代碼塊分成多個片段,每個片段執行一個簡單的任務,然后在每個片段前添加注釋,引導讀者即將發生什么。

    // 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();
    ......
    
  5. Align comments in consecutive lines
  6. 對于多行且每行后都緊跟著注釋的情況,我們應該排列這些注釋,使它們更易讀懂。

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

    一些開發人員用Tab來排列注釋,其他的則用空格。最佳途徑還是用空格,因為在各種編輯器和IDE中,tab鍵的行為多種多樣。

  7. Don’t insult the reader’s intelligence
  8. 避免顯然的注釋,比如:

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

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

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

  11. Get to the point
  12. 不要寫無關你要傳達意思的注釋。避免笑話,詩歌和贅言。簡而言之,保持注釋簡潔,直接。

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

  15. Use special tags for internal use
  16. 團隊開發時,采用一致的一套標簽作為程序員間的溝通。比如,很多團隊使用“TODO:”標簽來指出需要附加編寫的代碼段:

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

    標簽注釋并不解釋代碼,它們往往尋求注意或傳遞信息。但是,如果你用這種方法,務必將你要傳遞的信息寫上。

  17. Comment code while writing it
  18. 在編寫代碼是添加注釋,此時它們在你腦中還是清晰的。如果你直到最后才來添加,將事倍功半。“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 
    }
    
  19. Write comments as if they were for you(in fact,they are)
  20. 注釋代碼時,不僅僅要考慮其他開發人員以后可能會維護你的代碼,也要考慮你自己。 偉大的Phil Haack曾說過:"As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code."

    結果,我們自己將是優良(笨拙)注釋的第一個受益(害)者。

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

  23. The golden role of comment:readable code
  24. 程序員的基本功之一:讓你的代碼為自己說話。盡管一些不喜歡寫注釋的人懷疑這是程序員們瞎編亂造的,不過事實是自明的代碼對于編寫更易懂的代碼甚至使注釋變的不必要有很好的幫助。例如,在我的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),確保正確的縮排和采用代碼樣式指南。不遵守這條提示的結果可能是注釋看起來象似向糟糕的代碼道歉。

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

本文地址:http://www.zqhthc.tw/librarys/veda/detail/725,歡迎訪問原出處。

不打個分嗎?

轉載隨意,但請帶上本文地址:

http://www.zqhthc.tw/librarys/veda/detail/725

如果你認為這篇文章值得更多人閱讀,歡迎使用下面的分享功能。
小提示:您可以按快捷鍵 Ctrl + D,或點此 加入收藏

大家都在看

閱讀一百本計算機著作吧,少年

很多人覺得自己技術進步很慢,學習效率低,我覺得一個重要原因是看的書少了。多少是多呢?起碼得看3、4、5、6米吧。給個具體的數量,那就100本書吧。很多人知識結構不好而且不系統,因為在特定領域有一個足夠量的知識量+足夠良好的知識結構,系統化以后就足以應對大量未曾遇到過的問題。

奉勸自學者:構建特定領域的知識結構體系的路徑中再也沒有比學習該專業的專業課程更好的了。如果我的知識結構體系足以囊括面試官的大部分甚至吞并他的知識結構體系的話,讀到他言語中的一個詞我們就已經知道他要表達什么,我們可以讓他坐“上位”畢竟他是面試官,但是在知識結構體系以及心理上我們就居高臨下。

所以,閱讀一百本計算機著作吧,少年!

《數據結構與算法分析:C++描述(第3版)》 維斯 (Mark Allen Weiss) (作者), 張懷勇 (譯者), 等 (譯者)

《數據結構與算法分析:C++描述(第3版)》是數據結構和算法分析的經典教材,書中使用主流的程序設計語言C++作為具體的實現語言。書的內容包括表、棧、隊列、樹、散列表、優先隊列、排序、不相交集算法、圖論算法、算法分析、算法設計、攤還分析、查找樹算法、k-d樹和配對堆等。《數據結構與算法分析:C++描述(第3版)》適合作為計算機相關專業本科生的數據結構課程和研究生算法分析課程的教材。本科生的數據結構課程可以使用《數據結構與算法分析:C++描述(第3版)》第1章~第9章,多學時課程還可以講解第10章;研究生算法分析課程可以使用第6章~第12章。

更多計算機寶庫...

英超直播吻球网