你是否曾在檢查代碼時(shí)碰到一條在你看來多余的注釋？在代碼中使用注釋的目的是提升代碼的可讀性，以讓那些非原始代碼開發(fā)者能更好地理解它們。

我甄別出5類讓我不勝其擾的注釋及5類生成它們的程序員。我希望讀過本篇之后，你不會(huì)與他們一樣墜入同一條河流。作為一項(xiàng)挑戰(zhàn)，你不妨把寫這5類注釋的程序員與5類程序員[英文]作一下匹配。

1. 驕傲型程序員

public class Program  
{  
    static void Main(string[] args)  
    {  
        string message = "Hello World!";  // 07/24/2010 Bob  
        Console.WriteLine(message); // 07/24/2010 Bob  
        message = "I am so proud of this code!"; // 07/24/2010 Bob  
        Console.WriteLine(message); // 07/24/2010 Bob  
    }  
} 

這類程序員對(duì)其代碼自視甚高，以至于他覺得有必要在每行代碼后都要簽上自己的大名。應(yīng)用版本控制系統(tǒng)（VCS）是能知道誰(shuí)修改了代碼，但是乍看之下責(zé)任人也不會(huì)如此打眼。

2. 過時(shí)型程序員

public class Program  
{  
    static void Main(string[] args)  
    {  
        /* This block of code is no longer needed  
         * because we found out that Y2K was a hoax  
         * and our systems did not roll over to 1/1/1900 */ 
        //DateTime today = DateTime.Today;  
        //if (today == new DateTime(1900 1 1))  
        //{  
        //    today = today.AddYears(100);  
        //    string message = "The date has been fixed for Y2K.";  
        //    Console.WriteLine(message);  
        //}  
    }  
} 

如果一段代碼不再使用了（也就是過時(shí)了），請(qǐng)刪除它——勿要讓你的工作代碼被數(shù)行冗余的注釋弄得七零八亂。而且，你任何時(shí)候需要復(fù)制這段刪除的代碼，都可以使用版本控制系統(tǒng)，這樣你便能從以前版本中恢復(fù)出它來。

3. 顯然型程序員

public class Program  
{  
    static void Main(string[] args)  
    {  
        /* This is a for loop that prints the   
         * words "I Rule!" to the console screen   
         * 1 million times each on its own line. It  
         * accomplishes this by starting at 0 and   
         * incrementing by 1. If the value of the   
         * counter equals 1 million the for loop  
         * stops executing.*/ 
        for (int i = 0; i < 1000000; i++)  
        {  
            Console.WriteLine("I Rule!");  
        }  
    }  
} 

我們都知道編程的基本工作邏輯——這可不是什么“編程入門”！你無(wú)需浪費(fèi)時(shí)間解釋顯而易見的程序工作原理，雖然我們很高興看到你愿意解釋代碼的功能——但這不過是畫蛇添足。

4. 傳記型程序員

public class Program  
{  
    static void Main(string[] args)  
    {  
       /* I discussed with Jim from Sales over coffee   
        * at the Starbucks on main street one day and he  
        * told me that Sales Reps receive commission   
        * based upon the following structure.   
        * Friday: 25%  
        * Wednesday: 15%  
        * All Other Days: 5%  
        * Did I mention that I ordered the Caramel Latte with  
        * a double shot of Espresso?   
       */ 
        double price = 5.00;  
        double commissionRate;  
        double commission;  
        if (DateTime.Today.DayOfWeek == DayOfWeek.Friday)  
        {  
            commissionRate = .25;  
        }  
        else if (DateTime.Today.DayOfWeek == DayOfWeek.Wednesday)  
        {  
            commissionRate = .15;  
        }  
        else 
        {  
            commissionRate = .05;  
        }  
        commission = price * commissionRate;  
    }  
} 

如果你非得在代碼中提到某些必需的東西，也別提到人名。Jim from Sales（譯注：銷售人員Jim）也許離開這家公司了，那些閱讀代碼的程序員極可能根本就不知道他是誰(shuí)，更甭提注釋里那些毫無(wú)干系的事情。

5. “總有一天”型程序員

public class Program  
{  
    static void Main(string[] args)  
    {  
       //TODO: I need to fix this someday – 07/24/1995 Bob  
       /* I know this error message is hard coded and  
        * I am relying on a Contains function but   
        * someday I will make this code print a   
        * meaningful error message and exit gracefully.  
        * I just don’t have the time right now.  
       */ 
       string message = "An error has occurred";  
       if(message.Contains("error"))  
       {  
           throw new Exception(message);  
       }  
    }  
} 

這類注釋在某種程度上說是前面幾種類型的大雜燴。TODO注釋在項(xiàng)目初始開發(fā)階段用處不小，但是如果幾年后出現(xiàn)在產(chǎn)品代碼中——那就會(huì)帶來麻煩。如果有什么需要修補(bǔ)的，趁現(xiàn)在動(dòng)手，而不要推遲到以后去做。

如果你不幸是生成這些類型注釋的人，或者你想學(xué)習(xí)注釋用法的***實(shí)踐，我推薦你閱讀Steve McConnell寫的Code Complete（《代碼大全》）。這是一本我建議程序員必讀的書籍，OSC地址 http://my.oschina.net/justjavac/blog/66624。

你是否在自己的代碼中看到了其它類型多余或擾人的注釋？請(qǐng)不吝分享。

原文鏈接：http://www.oschina.net/question/253614_79956