先說結論：註解必須寫，除非 code 太過簡單。
我不相信有「看得懂的命名」這東西。
哪怕是我現在全部寫中文，發到網路上，
只要字數多到一個程度，就會有一堆人看不懂中文表達的意思。
更不用說是程式碼。
連命名都看不懂，就更要花大量的時間去釐清整個 code 的邏輯才看得懂「寫什麼」。
看懂寫什麼之後，更重要的是看懂「為什麼」這樣寫。
而註解，就是一個省下看得懂「寫什麼」跟「為什麼」時間的好東西。
然而，會議跟文件是碼農最大的敵人，
在某種程度上，註解也是。
所以註解，在精不在多，在關鍵不在詳細。
註解和 code 是完全相依的，
如果註解既繁且雜沒重點，那基本上 code 是垃圾的可能性很高。
善於寫 code 的人，要鍛練自己寫註解的能力。
最好別人不用去 trace code，只要看一遍註解，就可以接手。
所以好的註解，可以引導別人的思路，就跟寫小說一樣。
－－－
這就又回到如何寫 code 的命題，這裡舉個例，
每個人習慣不一樣，所以姑且參考。
我個人很喜歡 if，但非常討厭 else。
if 是可控的，else 不可控，思慮再慎密的人，都會敗在 else。
透過許多可控的 if，邏輯一脈相承，註解寫起來就非常輕鬆，
只要解釋為什麼我要用這些 if，跟這些 if 在做什麼事。
也許 if 太多很難看，把許多 if 精簡後變成短短幾行看起來非常炫，
但對於要理解 code 的人來說，反而是要在大腦裡把這短短幾行，
拆開並還原成所有的 if 條件，再去逐一理解－－浪費時間又容易錯。
把 if 歸納成 function 之後，對我來說沒有什麼功能是三個 block 無法說明的。
// if ..., do ...
case -> if -> handling
畫成 block diagram 就是一個唬弄客戶跟長官的好東西。
好吧這是題外話XD
也許寫完這個功能要數百行 code，但註解可能就十幾行。
解釋一下「寫什麼」(do) 跟「為什麼」(if) 就好。
如果註解寫成這樣
code .... code ... code ... // comment
在一行 code 後面還要註解這行在幹什麼，基本上就是一種失敗，
因為這表示別人連這一行 code 都得靠註解才看得懂。
失敗的不是註解，是 code 寫太爛。