用程式碼表達你的本意

適當地使用註解是用來『彌補我們用程式碼表達意圖的失敗』。注意，我使用了失敗這個字眼，我是認真的。......所以，當你發現你必須要寫註解的時候，先仔細思考，看看有沒有其它辦法來扭轉形勢，直接以程式碼來表現意圖。

我過去是學文學的人，在某種程度上我認為在一段文字裡使用括弧，是種不專業的做法，因為如果文章寫的好，是不需要另外使用這種額外註解的方法去說明。所有的資訊都應該在流暢的行文、描述中被傳達，而非生硬的補充說明；我大學時修了一堂電影敘事的課程，教授告訴我們，在電影中如果使用了旁白，某個程度上代表該電影的水準不夠，因為電影應該讓畫面、劇情來說話，而非藉由旁白來敘事。只有當我們功力不足時，才會讓旁白去補足缺失的地方。

而如今，Uncle Bob 告訴我，當我們去使用註解的時候，我們就已經失敗了。寫註解的某個動機及理由，是因為程式寫的太糟糕。而作為一個讀文學的人，我能理解他。

與其花時間寫註解來解釋你造成的混亂，不如花時間去整理那堆混亂的程式碼。

無益的註解

由於絕大多數的註解都是無益的，而且作者認為在最好的情況下，註解也不過是一種必要之惡，為什麼呢？因為它們說謊。

也許不總是如此，也許不是故意，但時常註解都會偏離真實，尤其當程式碼存在的時間越來越久時。
原因很簡單，程式設計師們沒有確實地維護它們。事實上，我甚至沒聽過有人會去維護註解。可是程式碼會修改，被搬移、被分離、被重製，所以縱然原本註解是真確的，也將變的錯誤百出。而這樣的錯漏甚至會誤導其他人的使用，導致最後程式的 bug。

而這還是原本堪用的註解，有些註解從開始就不該存在。

我們多少都會看過或甚至製造過一些註解，版本的說明、程式不需要但想留下的程式碼、出處或署名......等等。這在過去也許是可以被理解的，但現在我們已經有了版控系統，我們幾乎都在使用 git。你可以相信它，在儲存這些事情上它永遠比我們做的更好。

我們還看過什麼樣的註釋？開發過程中的喃喃自語、跟程式的對話、重新陳述程式碼中很明顯的事實。這些程式碼除了沒必要，而且還極度干擾。而我自己也真的寫過，在註解中用不正經的口語解釋程式碼，排解抑鬱。

與其宣洩在一個無用又會產生干擾的註解裡，程式設計師應該有另一個認知，透過改善程式的結構，他的沮喪就可以被排解。......將製造『干擾字詞的誘惑』轉化成『改善程式碼的決心』，你將發現自己成為一位更優秀且更快樂的程式設計師。

有益的註解

某些時候，註解的存在是可以被理解及認同的。

• 法律型

  有時候，公司的程式撰寫標準規範，會強迫我們必須寫下某些關於法律方面的註解。舉例來說，在每個原始碼檔案的開頭寫入著作權聲明及作者資訊，就是必須且合理的註解。

• TODO

  以 // TODO 的型式留下代辦，某些時候是合理的。但切記，定期審視並清理不再需要的代辦事項。

• 公共 API

  沒有什麼比一個良好描述公共 API 更有用處和令人滿意了。......但也要記住本章其他部分的建議，Javadoc 也可能像其他任何的註解一樣，產生誤導性、非區域性及非誠實性的現象。

小結

看完關於註解的內容後，對於自己的一種註解猶豫了很久，但最後還是留下了。
我是一個英文不好的人，對較少用的變數名會看不懂或看很慢，所以習慣在變數的正上方註解他的中文，以利自己辨識。我不知道這樣好不好，但我想如果以「明確的意圖」、「容易閱讀、理解」的角度為出發點，這樣註解應該不過份 吧？