程式設計師應該避免的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
    }
}

這個程式設計師自認為寫了一段很了不得的程式碼，所以覺得有必要用自己的名字對每行程式碼進行標記。實施版本控制系統（VCS）能實現對程式碼變更的問責，但是也不會這麼明顯知道誰應對此負責。

2.過時的程式設計師

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.多此一舉的程式設計師

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

我們都知道基礎的程式設計邏輯是如何工作的——所以你不需要多此一舉來解釋這些顯而易見的工作原理，雖然說你解釋得很happy，但這只是在浪費時間和空間。

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可能會離開公司，而且很有可能大多數程式設計師根本不知道這是何許人也。不要在註釋裡提及不相干的事實。

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

這種型別的註釋包含了上面所有其他型別。如果是在專案的初始開發階段，這種待做註釋是非常有用的，但如果是在幾年後的產品程式碼——那就會出問題了。如果有什麼需要修復的，立馬解決，不要把它擱置一邊，“以後再做”。

如果你也常常犯這樣的註釋錯誤，如果你想了解註釋的最佳做法，我建議你閱讀類似於Steve McConnell寫的《Code Complete》這樣的好書。

另外筆者也推薦你閱讀以下內容：《9個最有趣的程式碼註釋》、《程式碼註釋中的5要與3不要》