程序員應該避免的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》這樣的好書。
譯文鏈接：http://www.codeceo.com/article/5-types-comment-we-avoid.html
英文原文：5 Types of Programming Comments to Avoid
翻譯作者：碼農網 – 小峰