5類應避免使用的代碼注釋

來源: 譯言網發布時間: 2011-11-19 21:54 閱讀: 2271 次推薦: 0 原文鏈接 [收藏]

　　英文原文：5 Types of Comments to Avoid Making in Your Code

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

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

　　1. 驕傲型程序員(The Proud Programmer)

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
    }
}

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

　　2. 過時型程序員(The Obsolete Programmer)

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);
        //}
    }
}

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

　　3. 顯然型程序員(The Obvious Programmer)

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!");
        }
    }
}

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

　　4. 傳記型程序員（The Life Story Programmer）

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）也許離開這家公司了，那些閱讀代碼的程序員極可能根本就不知道他是誰，更甭提注釋里那些毫無干系的事情。

　　5. 總有一天型程序員（The Someday Programmer）

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);
       }
    }
}