遠離程式碼註釋的 5 個理由

　　免責宣告：我所說的“避免程式碼註釋”並不意味著我不寫註釋，這意味著，我儘可能避免寫程式碼註釋，但當我覺得值得寫時我還是寫的。

　　“相比寫軟體我們花了更多的時間在閱讀軟體上”，一直以來我沒有見過任何科學研究證明了這一點，但在軟體領域，它就像一個教條或一個共同的信念。由於它的存在，將軟體寫得易於閱讀、關注程式碼的可讀型都是很重要的。通過一些技術的輔助程式設計師可以實現這些要求，這些技術其中之一就是寫程式碼註釋。

　　當談論起程式碼註釋的時候，有關的辯論總無休止。我們應該用註釋來說明我們程式碼的作用嗎，我們應該將重點放在程式碼的表達性而不需要註釋來輔助閱讀嗎？Joe Kunk為這爭論寫了一篇部落格 - 應不應該寫註釋。有那些人說文件完備的程式碼被認為是好程式碼，還有些人說應該避免註釋，因為註釋通常被用來解釋/隱藏不好的程式碼。

　　在我看來，在書籍的影響下，為確保程式碼整潔便於重構，我們應該避免寫註釋，除非我們有一個好的寫註釋的理由（例如數學演算法）或因為公司要求或流程我們有義務這樣做。下面是我關於註釋的五點憂慮。

　　我認為程式碼註釋起到反作用的地方

　　1.註釋往往鼓勵壞的程式碼。“註釋的程式碼是好程式碼”有這樣一個說法，所以人們常常在程式碼中新增註釋以程式碼漂亮。如果我們為了解釋程式碼而新增註釋這就像是一個訊號：也許我們正在編寫糟糕的程式碼。當我們要寫一條註釋是，我們應該想是否能夠通過清理程式碼使它更有可讀性呢。

　　2. 我們將花費更多的時間來編寫和維護。註釋通常是程式碼的第二個版本。當我們為一個函式寫註釋時我們實際在重複自己。我們違背了DRY（不要重複自己）原則。我們正在花費更多的時間且增加了複雜性。需求如果變了程式碼也要跟著變，如果我們寫了註釋也要隨之更改。所以為多花費的一倍時間做出改變吧。我們可以利用這段時間來提高我們的程式碼或開發新的功能。

　　3. 註釋是不可測試和驗證的。當我們修改程式碼的時候我們藉助諸如編譯器、IDE及單元測試工具來輔助，註釋沒有，沒有類似工具。你無法依靠工具或單元測試來確保它們的使用位置、日期標註等是正確的。一旦你寫了一條註釋，因為它是不可測試的無法關注它的準確性，一旦出錯便會無法察覺的保留下來。

　　4. 與程式碼相比註釋是不可靠的。通常當註釋和程式碼脫離它就變得與沒有多大意義了。如果程式設計師讀到它就可能被誤導。即使沒有誤導也需要通過閱讀原始碼來搞清到底做了什麼。一個實際的例子，如果我們的老闆需要我們做一個修改，我們應該看註釋還是程式碼呢？當然我們會看程式碼。

　　5. 註釋佔用了不少螢幕空間。一些註釋方法（像下面的）佔了很多行，當你想檢視更多程式碼時這便成了一個問題。

/**
* 
* @param title The title of the CD
* @param author The author of the CD
* @param tracks The number of tracks on the CD
* @param durationInMinutes The duration of the CD in minutes
*/
public void addCD(String title, String author, 
int tracks, int durationInMinutes) {
CD cd = new CD();
cd.title = title;
cd.author = author;
cd.tracks = tracks;
cd.duration = duration;
cdList.add(cd);
}

　　原文地址：http://pauloortins.com/5-reasons-to-avoid-code-comments/