程式員應該避免的 5 種代碼注釋

你有沒有這樣的經曆：别人審查過你的代碼之後給出的注釋，你認為是沒有必要的？注釋代碼是為了提高代碼的可讀性，目的是為了能讓其他人更容易了解你的代碼。

我特别讨厭這5種注釋類型以及制造它們的程式員。希望你不是其中之一。

<a target="_blank"></a>

<code>public class program</code>

<code>{</code>

<code>static void main(string[] args)</code>

<code>string message = "hello world!"; // 07/24/2010 bob</code>

<code>console.writeline(message); // 07/24/2010 bob</code>

<code>message = "i am so proud of this code!"; // 07/24/2010 bob</code>

<code>}</code>

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

<code>/* this block of code is no longer needed</code>

<code>* because we found out that y2k was a hoax</code>

<code>* and our systems did not roll over to 1/1/1900 */</code>

<code>//datetime today = datetime.today;</code>

<code>//if (today == new datetime(1900, 1, 1))</code>

<code>//{</code>

<code>// today = today.addyears(100);</code>

<code>// string message = "the date has been fixed for y2k.";</code>

<code>// console.writeline(message);</code>

<code>//}</code>

如果一段代碼已不再使用（即過時），那就删除它——不要浪費時間給這些代碼寫注釋。此外，如果你需要複制這段被删除的代碼，别忘了還有版本控制系統，你完全可以從早期的版本中恢複代碼。

<code>/* this is a for loop that prints the</code>

<code>* words "i rule!" to the console screen</code>

<code>* 1 million times, each on its own line. it</code>

<code>* accomplishes this by starting at 0 and</code>

<code>* incrementing by 1. if the value of the</code>

<code>* counter equals 1 million the for loop</code>

<code>* stops executing.*/</code>

<code>for (int i = 0; i &lt; 1000000; i++)</code>

<code>console.writeline("i rule!");</code>

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

<code>/* i discussed with jim from sales over coffee</code>

<code>* at the starbucks on main street one day and he</code>

<code>* told me that sales reps receive commission</code>

<code>* based upon the following structure.</code>

<code>* friday: 25%</code>

<code>* wednesday: 15%</code>

<code>* all other days: 5%</code>

<code>* did i mention that i ordered the caramel latte with</code>

<code>* a double shot of espresso?</code>

<code>*/</code>

<code>double price = 5.00;</code>

<code>double commissionrate;</code>

<code>double commission;</code>

<code>if (datetime.today.dayofweek == dayofweek.friday)</code>

<code>commissionrate = .25;</code>

<code>else if (datetime.today.dayofweek == dayofweek.wednesday)</code>

<code>commissionrate = .15;</code>

<code>else</code>

<code>commissionrate = .05;</code>

<code>commission = price * commissionrate;</code>

如果你一定要在注釋裡提及需求，那麼不要涉及别人的名字。銷售部門的jim可能會離開公司，而且很有可能大多數程式員根本不知道這是何許人也。不要在注釋裡提及不相幹的事實。

<code>//todo: i need to fix this someday - 07/24/1995 bob</code>

<code>/* i know this error message is hard coded and</code>

<code>* i am relying on a contains function, but</code>

<code>* someday i will make this code print a</code>

<code>* meaningful error message and exit gracefully.</code>

<code>* i just don't have the time right now.</code>

<code>string message = "an error has occurred";</code>

<code>if(message.contains("error"))</code>

<code>throw new exception(message);</code>

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

如果你也常常犯這樣的注釋錯誤，如果你想了解注釋的最佳做法，我建議你閱讀類似于steve mcconnell寫的《code complete》這樣的好書。本文來自雲栖

社群合作夥伴“linux中國”，原文釋出日期：2015-10-02