5類應避免使用的代碼注釋
你是否曾在檢查代碼時碰到一條在你看來多余的注釋？在代碼中使用注釋的目的是提升代碼的可讀性，以讓那些非原始代碼開發者能更好地理解它們。
我甄別出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); } } }
這類注釋在某種程度上說是前面幾種類型的大雜燴。TODO注釋在項目初始開發階段用處不小，但是如果幾年后出現在產品代碼中那就會帶來麻煩。如果有什么需要修補的，趁現在動手，而不要推遲到以后去做。
如果你不幸是生成這些類型注釋的人，或者你想學習注釋用法的最佳實踐，我推薦你閱讀Steve McConnell寫的Code Complete（《代碼大全》）。這是一本我建議程序員必讀的書籍。
或者你也可以徹底點，學習怎樣不使用代碼注釋。
你是否在自己的代碼中看到了其它類型多余或擾人的注釋？請不吝分享。
