# 虎年行大運 ~ Clean Code 系列 - 註解

## 【前言】
最近開始看 Clean Code 了，接下來會做關於書中內容的心得與個人經驗整理的分享文。

## 【主文】
**「最好的註解，就是沒有註解。」**
如果說遵守 Clean Code 的設計準則夠徹底，那其實需要寫註解的時候真的不多。

如果難免碰到有需要的時候，可能是一段解釋、一段說明、一段心理歷程(?)。無論如何，註解的存在一如身為一個幫助開發人員釐清程式碼的前輩一般重要。

註解與程式碼的重要程度幾乎相當，一個不清楚的註解可以完全催毀一段程式碼。相反，一個好的註解，再不清楚的程式碼也可能在短時間內被解譯(?)出來。

你其實不需要註解，但當你需要的時候，會對他又愛又恨。愛的是有他真好，恨的是為什麼需要他。

## 【書中的大道至簡】
我們首先先認識何謂有效益的註解，後面再看何謂不好的註解。

> Kai 的學習方式喜歡先學正確的東西，因為一件事物往往最初的內容就會是最深、刻最有印象的，所以都先學正確的，再學反面的衝擊力會更強、印象也會越深刻。

- **有效益的註解**
- **法律相關的註解**
有些公司為了標記財產所有權，或是為了統一的開發規範，不免會要求在系統上、程式內寫上關於公司資訊、著作權、財產權所屬等內容。如果這些資訊是統一在行頭或行尾的話，便有辦法透過 IDE 的設定去隱蔽。但這類型的資訊，也許還是交由一個統一的檔案或地方做證明就夠了，程式碼的部分盡量還是保持清晰為主。
- **資訊相關的註解**
透過註解去更仔細的說明放入參數、回傳參數等內容、針對物件、方法、參數等提供使用上的訊息或者意圖都對開發人員有一定程度的幫助。但不要過分詳細的解釋，簡潔有達到目的即可。不要讓太多訊息佔據了開發版面。
- **闡明**
有時候直接說明意圖或結果的方式更容易讓人快速了解內容，而不一定要透過研讀程式碼。
- **警告、強調重要性**
某些具備開啟或關閉功能的程式碼部分，通常會明確寫下一些警告類的註解，告訴你這東西可能使用上要注意什麼? 使用後會有什麼結果? 這種狀況是無法透過命名的處理去解決。但可以的話... 類似的東西還是少做，如果真有什麼會需要過份注意的部分，能透過其他工具處理就不要放進程式碼內當特例。除了那些專門用於測試的類別。
又或者是為了加以強調或提醒的訊息，這部分的確可以提供比較多支援，幫助開發者容易理解某個特定的部分是核心或需要避開一些地雷，慎重待之。但 Kai 相信如果真的有這麼重要的部分，更應該在基本的員工素質訓練時就說明到位。
- **Javadoc**
唯一你能夠詳細書寫註解的部分，大概只有在開發公共 API 的時候，因為沒有什麼東西比註解更好的去解釋與說明這些 API 的內容了。

看完了有效益的註解後，來看看沒效益的部分。

- **沒效益的註解**
- **喃喃自語**
千萬! 千萬! 不要把你個人想說的話寫在程式碼內，千萬! 不要! 其他人不會想知道你到底經歷了什麼才會留下這些毫無幫助的訊息。記住! 當你要寫註解的時候，就已經證明你在命名與函式的處理上無法明確表達邏輯或業務方面的訊息，你必須更加珍視即將寫出的註解，因為這些東西將會大大地影響其他閱讀的人的理解。
- **冗餘**
註解的訊息量不應該太多，這會讓開發者疲於閱讀，造成生產力與理解力的下降，用字遣詞應該以簡單為主。且就算要認真說明該程式碼的構思來源，請不要把整篇來源文章貼上來，可以標記一個網址即可，但更好的方式是應該額外有一份產品的文件，在該功能的部份去指引說參考了哪些網站內容為佳。
- **誤導**
這種類型的註解最為可怕，因為大多數的開發人員都是良善的，他們會選擇去相信那些只有一行的註解，勝於閱讀數十多行的程式碼邏輯。而不清楚甚至指引錯誤方向的註解則會造成更多的錯誤發生。
另外還有一種誤導的可能，是因為程式更新後區塊的位移造成的，原先的註解可能說的是 A 方法，但是中間被某一位開發者插進了一個 B 方法後，整個註解的解釋區塊就不對了，因此後續維運人員可能就誤認為註解是在說明 B 方法。
註解不僅需要寫得好，更需要時刻與程式碼一同更新，以免造成誤導的錯誤。因此歸根究底來說，還是少寫註解吧~
- **干擾**
重複的訊息、或已經藉由命名與函式處理好的部分不需要註解，更不需要詳盡說明的註解，這會讓開發人員很惱火，他可能出自於善意不方便刪除前人遺留的東西，但這絕對干擾開發。
此外，也不需要一行程式碼配一行註解，接手維運的人一定會想殺死你的~
干擾型的註解還會產生壞習慣，當接手的開發人員因為習慣性地去避開閱讀註解後，可能就會錯失真正重要訊息的部分，屆時出錯了的話究竟責任應該在誰身上呢? Kai 誠心的期望自己不要成為這種會遺留技術債的人。
- **規定類註解**
這種註解某種程度來說是公司產品一致性的表現，照理說應該不會是沒效益的註解，但 Kai 個人認為這種因為規範下必須留下來跟程式可能無關的東西就是沒效益的作法。人的閱讀與理解能力在一天當中是有數量限制的，在無法記得太多東西的情況下，不應該閱讀那些因為規範下不得不寫進去；實際可能沒任何效益；有礙觀瞻的東西。
- **日誌**
現在已經有很多開源的版控軟體可以使用了，無論是程式開發、大型文件的處理、資料庫的運行都有很多種類的版控軟體可以使用，不要在把這些更新訊息透過註解寫在程式碼中了。盡量只保留可以用於加強說明或重點告知、與現行功能或邏輯有關的就好。
- **無用的程式碼**
有了版控軟體的幫助，你隨時可以回顧這些被刪去的程式碼部分，所以不要把他們註解起來當備用了，該刪就刪，事實證明有很多註解起來的程式碼是你可能永遠不會再使用到。
- **出處或署名**
如果說法律類相關的註解有其效用的話，那出處或署名這類型的就可以說是沒必要了，如同之前所言，你有可以很好說明這類型訊息的地方，就是你的產品文件或公司文件，這些訊息沒必要存放在程式碼中，除非他們本身具備了某種程度上的法律效益。
- **HTML型式註解**
HTML 型的註解結構十分難看且不友善，盡可能的少用為妙。註解還是以簡單說明為主，如果需要為了裝飾這些文字而有了排版，請先思考一下為何需要這麼多訊息呢?

尚有一些不一定有效益、但用不好可能帶來更多負面效果的註解使用方式

- **不好不壞的註解**
- **TODO**
這類型的註解應該很多人碰過，也常常在程式中看到。它的存在主要是為了提醒開發人員有尚未完成、應該被完成的項目，這是它最大的效益。目前許多 IDE 都內建有詳列所有 TODO 的功能。但說實話，這種註解不應該存在，該完成的東西就該好好完成，倘若有未完成的部分且不是因為進度的關係，是為了應對未來的可能性，那就該好好思考這種架構設計有沒有違背了 S.O.L.I.D 原則的 L 或 I 部分呢? 我想答案呼之欲出。
- **標記位置**
有些註解本身是為了讓開發人員更好的去辨識區塊，這種在大方向的處理上通常都是加分的，但要注意的是，避免過多的使用到這種方式，如果有，請必須先思考一下該方法或物件符合 S.O.L.I.D原則嗎? 通常這種有很多作業區塊的時候都是不符合的哦!
- **括號歸屬**
有些開發人員會藉由在括號後面添上註解，以此註記屬於哪一個處理的區塊。這有可能是因為中間夾雜過多的程式碼導致篇幅占用數十行造成的閱讀困難，但現今大多 IDE 都有強調括號所屬的功能，即便是 NOTEPAD++ 都有，因此要快速查找括號對應的所屬應該不是件難事。當然適當的運用也可以幫助理解段落與邏輯。但過多就會造成干擾了。

## 【結語】
「在最好的情況下，註解也只不過是一種必要之惡。」出自書中該篇章的首頁。

能寫出不需要註解的程式碼，你當為自己歡呼叫好，好好讚美自己一番。
反之，應當好好反省自己的表達敘事能力的不足，必須要依靠註解的幫助才能傳達意思。

當然大多數的實際業務來說，或多或少還是需要註解的點綴吧~?

首頁 [Kai 個人技術 Hackmd](/2G-RoB0QTrKzkftH2uLueA)

###### tags: `Clean Code 無瑕的程式碼`