一、前言
這篇文章將會分享 Clean Code 關於註解的重點，內容主要以個人閱讀後心得為主，有興趣了解更多請自行購買這本書。
二、Clean Code
這本書出自於某一位程式設計的大師，他為程式設計建立了一個程式設計的流派，Clean Code 對每一位程式設計師的意義都不盡相同，對某些人來說，這是維護、命名的準則，對某些人來說，則是程式開發的架構與雛形。
1. 簡潔
這本書最為著名的就是簡潔，簡單扼要的程式邏輯、清楚易懂的程式設計知識與架構，這是它廣為流傳的核心守則，這本書不會實際教導如何寫程式，它會把寫程式要注意、要避免的事情一步步告訴設計師。2. 直覺
其中最重要的一件事情，是Clean Code 強調程式是一種語言，因此在撰寫裡面的每一個字都要設計與思考，就像寫一本書一樣，要能讓人一看就懂，不需要經過轉化或推測，能很直覺的就理解程式碼的內容，因此也容易維護。
3. 零重複
它的一項特徵是程式碼不會有重複的內容，同一功能的程式寫完之後就不用再撰寫第二次，能讓程式碼的數量大為減少，重複利用的同時依然保持單一職責的設計模式。
三、註解
學習程式碼的過程中，自然而然的就學會了註解；在很多插件裡面也能看到註解；那我們應該怎麼使用註解比較好呢？
1. 不要替糟糕的程式碼寫註解──重寫它
我們決定對程式碼註解的原因，很有可能是我們擔心程式碼太亂，容易讓下一位讀者看不懂這段程式碼在寫什麼，因此我們添加了一個註解，告訴他們這段程式碼的一些備註。
寫程式像寫文章一樣，如果覺得看不太懂，重寫就對了；不要為了文章寫不清楚而註解，我們應該直接重寫一遍，直到我們覺得這段文章直接看就能理解功能，不需要額外備註。
2. 有益的註解概述
真正有意義的註解，剛好是那些有實際意義的註解，它們會向文章本身，缺少就會有一種空缺感，而不是缺少後依然能順利讀下去；我會挑選幾個我認為對寫程式有幫助的註解類型跟大家分享。
3. 糟糕的註解概述
有些註解去掉之後，對程式碼內容並無顯著影響；有些註解被撰寫後，反而影響程式碼的閱讀；這些註解都對程式碼都沒有正向效益，因此都是不應該存在於程式碼的內容。
四、有益的註解
有必要才要註解，因此有益的註解就是那些絕對不能少的註解。
1. 法律型註解
你可能有看過法律型的註解，它會告訴你這份程式碼腳本是來自於哪家公司所設計，請不要隨意的轉載或修正等等，總之就是告訴你這份程式碼的智慧財產權歸屬。
法律型註解是概念意義上的重要，實際上對寫程式碼沒有幫助，就像是申請商標一樣的概念，是一種對自己的保護，所以這種註解該寫還是要寫，雖然我們普通程式設計師應該不會接觸到就是了。
2. 對後果的告誡
某一些程式的存在很便捷，但不可挽回；某一些程式的效用很特殊，不能隨便亂使用；某一些程式的功能會在某些狀況銷毀；類似上述的程式碼，我們都應該要在前面註解，告訴未來的使用這這個程式碼的危害。
3. TODO註解
善用尚未存在的程式碼，或者說我們未來打算這樣做的程式碼，都很值得使用ＴＯＤＯ來註解，現在程式編輯器都能使用搜尋來找到所有的ＴＯＤＯ程式碼了，不過要記得隨時更新。
五、糟糕的註解
有哪些程式碼註解是「糟糕」的程式碼註解呢？
1. 喃喃自語
我相信有些人在寫訊息的時候總喜歡多加一些額外的備註（PS. 我很少這樣子做)；在心情不好的時候，留下一些自己的心情日誌，譬如這東西真的超級無敵難寫到爆炸之類的。
請避免這些行為，因為寫程式碼的重點在「可讀性」這件事情，請務必從寫程式的開始到專案的結束都保持這個習慣，喃喃自語的程式碼會拖延其他人閱讀程式碼的過程。
2. 干擾的註解
有些註解沒有必要，尤其是在講述程式碼怎麼運作的時候，我簡單舉例一下你就懂了（舉例是指給你一個範本，讓你比較好理解文章的內容），換成中文文章的註解，是不是有比較好理解了，所以請避免這件事情。
3. 誤導型註解
註解是有時效性的一件事情，請務必記得這一點，有一些註解在多次更新之後就失去了原本的意思，原本可能是跟註解內容相同沒錯，但是在多個版本之後就不是這麼一回事了。
4. 被註解的程式碼
我們都是有禮貌的人，不會隨意刪除看起來「很厲害」的東西，尤其是被註解起來的程式碼，你可能認為它很重要所以不敢動它，而實際上它可能早就失去當初的用途了。
5. 過多的資訊
千萬不要在程式碼裡面寫文章，哪怕寫程式與寫文章有多處雷同的地方：它們都是一種語言；它們都會敘述某些事情；它們都試圖在傳達某些概念等等，這也不是在程式碼腳本中開始寫文章的理由。
六、後記
我一直認為寫註解是一件「很酷」的事情，因為綠色搭配程式編輯器的顏色非常符合我對寫程式的印象，我認為這代表了專業，實際上並不是，寫註解是一件多於事情，尤其是為了寫註解而寫，那就更多於了。
1. 註解是很重要的事情
當然，註解是很重要的事情，它是協助程式員跟程式員之間溝通的橋樑，也是我們學程式中自然而然學會的一件基礎技能，我完全沒印象我是什麼時候知道註解這件事情的了。
2. 註解是不重要的事情
當然，註解畢竟是一種備註，所以如果能不使用註解，就盡量的不要使用註解，因為程式碼本身就具有閱讀性，請不要像對待魔法文字一樣，幫每一個盧恩文字標上註釋。
3. 程式碼本身就是文章
最後，我打算再強調一次，程式碼本身具有可讀性，寫程式跟寫文章都是為了讓讀者看懂，讓下一位閱讀這份文章的人，能理解這份程式是在做什麼，撰寫程式的根本邏輯，就是為了「可讀性」這一件事情而已。
