Unity C# | Clean Code #3 註解

一、前言

二、Clean Code

1. 簡潔

　　這本書最為著名的就是簡潔，簡單扼要的程式邏輯、清楚易懂的程式設計知識與架構，這是它廣為流傳的核心守則，這本書不會實際教導如何寫程式，它會把寫程式要注意、要避免的事情一步步告訴設計師。

2. 直覺

　　其中最重要的一件事情，是Clean Code 強調程式是一種語言，因此在撰寫裡面的每一個字都要設計與思考，就像寫一本書一樣，要能讓人一看就懂，不需要經過轉化或推測，能很直覺的就理解程式碼的內容，因此也容易維護。

3. 零重複

　　它的一項特徵是程式碼不會有重複的內容，同一功能的程式寫完之後就不用再撰寫第二次，能讓程式碼的數量大為減少，重複利用的同時依然保持單一職責的設計模式。

三、註解

1. 不要替糟糕的程式碼寫註解──重寫它

　　我們決定對程式碼註解的原因，很有可能是我們擔心程式碼太亂，容易讓下一位讀者看不懂這段程式碼在寫什麼，因此我們添加了一個註解，告訴他們這段程式碼的一些備註。

　　寫程式像寫文章一樣，如果覺得看不太懂，重寫就對了；不要為了文章寫不清楚而註解，我們應該直接重寫一遍，直到我們覺得這段文章直接看就能理解功能，不需要額外備註。

2. 有益的註解概述

　　真正有意義的註解，剛好是那些有實際意義的註解，它們會向文章本身，缺少就會有一種空缺感，而不是缺少後依然能順利讀下去；我會挑選幾個我認為對寫程式有幫助的註解類型跟大家分享。

3. 糟糕的註解概述

　　有些註解去掉之後，對程式碼內容並無顯著影響；有些註解被撰寫後，反而影響程式碼的閱讀；這些註解都對程式碼都沒有正向效益，因此都是不應該存在於程式碼的內容。

四、有益的註解

1. 法律型註解

　　你可能有看過法律型的註解，它會告訴你這份程式碼腳本是來自於哪家公司所設計，請不要隨意的轉載或修正等等，總之就是告訴你這份程式碼的智慧財產權歸屬。

　　法律型註解是概念意義上的重要，實際上對寫程式碼沒有幫助，就像是申請商標一樣的概念，是一種對自己的保護，所以這種註解該寫還是要寫，雖然我們普通程式設計師應該不會接觸到就是了。

2. 對後果的告誡

　　某一些程式的存在很便捷，但不可挽回；某一些程式的效用很特殊，不能隨便亂使用；某一些程式的功能會在某些狀況銷毀；類似上述的程式碼，我們都應該要在前面註解，告訴未來的使用這這個程式碼的危害。

3. TODO註解

　　善用尚未存在的程式碼，或者說我們未來打算這樣做的程式碼，都很值得使用ＴＯＤＯ來註解，現在程式編輯器都能使用搜尋來找到所有的ＴＯＤＯ程式碼了，不過要記得隨時更新。

五、糟糕的註解

1. 喃喃自語

　　我相信有些人在寫訊息的時候總喜歡多加一些額外的備註（PS. 我很少這樣子做)；在心情不好的時候，留下一些自己的心情日誌，譬如這東西真的超級無敵難寫到爆炸之類的。

　　請避免這些行為，因為寫程式碼的重點在「可讀性」這件事情，請務必從寫程式的開始到專案的結束都保持這個習慣，喃喃自語的程式碼會拖延其他人閱讀程式碼的過程。

2. 干擾的註解

　　有些註解沒有必要，尤其是在講述程式碼怎麼運作的時候，我簡單舉例一下你就懂了（舉例是指給你一個範本，讓你比較好理解文章的內容），換成中文文章的註解，是不是有比較好理解了，所以請避免這件事情。

3. 誤導型註解

　　註解是有時效性的一件事情，請務必記得這一點，有一些註解在多次更新之後就失去了原本的意思，原本可能是跟註解內容相同沒錯，但是在多個版本之後就不是這麼一回事了。

4. 被註解的程式碼

　　我們都是有禮貌的人，不會隨意刪除看起來「很厲害」的東西，尤其是被註解起來的程式碼，你可能認為它很重要所以不敢動它，而實際上它可能早就失去當初的用途了。

5. 過多的資訊

　　千萬不要在程式碼裡面寫文章，哪怕寫程式與寫文章有多處雷同的地方：它們都是一種語言；它們都會敘述某些事情；它們都試圖在傳達某些概念等等，這也不是在程式碼腳本中開始寫文章的理由。

六、後記

1. 註解是很重要的事情

　　當然，註解是很重要的事情，它是協助程式員跟程式員之間溝通的橋樑，也是我們學程式中自然而然學會的一件基礎技能，我完全沒印象我是什麼時候知道註解這件事情的了。

2. 註解是不重要的事情

　　當然，註解畢竟是一種備註，所以如果能不使用註解，就盡量的不要使用註解，因為程式碼本身就具有閱讀性，請不要像對待魔法文字一樣，幫每一個盧恩文字標上註釋。

3. 程式碼本身就是文章

　　最後，我打算再強調一次，程式碼本身具有可讀性，寫程式跟寫文章都是為了讓讀者看懂，讓下一位閱讀這份文章的人，能理解這份程式是在做什麼，撰寫程式的根本邏輯，就是為了「可讀性」這一件事情而已。