五種應該避免的代碼注釋

在酷殼，有很多文章都提到了代碼注釋，如：《十條不錯的編程觀點》、《優質代碼的十誡》、《整潔代碼的4個提示》、《惹惱程序員的十件事》等等。今天，某國外的程序員在這里列舉五種應該避免的程序注釋，我覺得比較有道理，但我覺得有少數幾個觀點也并不絕對。所以，我把原文的這五種應該避免的程序注釋羅列在下面，并放上原作者和我的個人觀點作為比較。希望對大家有用。

一、自戀型注釋

（注：原文為Proud，我覺得“自戀”更好一點）

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

原文：這樣的程序員對于自己的代碼改動非常驕傲和自戀，所以，他覺得需在在這些自己的代碼上標上自己的名字。其實，一個版本控制工具（如：CVS或Subversion）可以完整地記錄下所有的關于代碼的改動的和作者相關的一切信息，只不過不是那么明顯罷了。

陳皓：我同意原文的觀點。在我的團隊里也有這樣的事情發生。有段時間我認真思考過這樣的事情，是否應該把這樣的事情在代碼中鏟除出去。后來，我覺得，允許這樣的行為并不一定是壞事，因為兩點：

1. 調動程序員下屬的積極性可能更為重要。即然，這種方式可以讓程序員有驕傲的感覺，能在寫代碼中找到成就感，為什么要阻止呢？又不是什么大問題。
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);        //}    }}

原文：如果某段代碼不再使用了，那就應該直接刪除。我們不應該使用注釋來標準廢棄的代碼。同樣，我們有版本控制工具來管理我們的源代碼，在版本控制工具里，是不可能有代碼能被真正的物理刪除的。所以，你總是可以從以前的版本上找回你的代碼的。

陳皓：我非常同意這樣的觀點。只要你是廢棄的，就應該是刪除，而不是注釋掉。注釋并不是用來刪除代碼的。也許你會爭論到，在迭代開發中，你覺得被注釋的代碼很有可能在未來會被使用，但現在因為種種問題暫時用不到，所以，你先注釋著，然后等到某一天再enable它。所以你注釋掉一些未來會有的程序。在這樣的情況，你可以注釋掉這段代碼，但你要明白，這段代碼不是“廢棄”的，而是“臨時”不用的。所以，我在這里提醒你，請不要教條式地在你的程序源碼中杜絕這樣的注釋形式，是否“廢棄”是其關鍵。

三、明顯的注釋

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

原文：看看上面的例子，代碼比注釋還容易讀。是的，大家都是程序員，對于一些簡單的，顯而易見的程序邏輯，不需要注釋的。而且，你不需要在你的注釋中教別人怎么編程，你這是在浪費時間去解釋那些顯而易見的東西。你應該用注釋去解釋你的代碼功能，原因，想法，而不是代碼本身。

陳皓：非常同意。最理解的情況是你的代碼寫得直接易讀，代碼本身就是自解釋的，根本不需要注釋。這是最高境界。注釋應該說明下面的代碼主要完成什么樣的功能，為什么需要他，其主要算法怎么設計的，等等。而不是解釋代碼是怎么工作的。這點很多新手程序員都做得不夠好。別外，我需要指出的是，代碼注釋不宜過多，如果太多的話，你應該去寫文檔，而不是寫注釋了。

生活不易，碼農辛苦
如果您覺得本網站對您的學習有所幫助,可以手機掃描二維碼進行捐贈