Re: [請益] 寫註解到底是不是好習慣

[babelism (Bob)]

先說結論：註解必須寫，除非 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 寫太爛。

--
ps1.
我年輕時喜歡弄一堆漂亮的 block diagram，
什麼 function flow, data flow 的，
現在我認為那都是屎。

程式架構應該是只要一張表格加上代碼本身自帶的註解就足夠讓人了解了。
--
ps2.
我絕對沒有在婊 Linux kernel 架構圖的意思，
畢竟好的架構圖絕對是有助於了解整體程式碼結構的。
--
ps3.
寫 comment 的時候，把對象想像成一隻猴子有益無害。
--
ps4.
這篇寫到後來本來覺得煩想刪掉，
但想想辛苦寫了這麼久，還是賺個p幣好了。

--
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 59.127.94.119
※ 文章網址: https://www.ptt.cc/bbs/Soft_Job/M.1546008917.A.C92.html
推 Astar5566: doxygen大法好
→ Astar5566: 看開源專案少之又少的註解真的是種磨練
→ Ghamu: 我覺得我的code是越寫越簡單 拆分越來越細 不太懂你說除非
→ Ghamu: 程式碼很簡單是什麼意思 工程師不是本來就應該要寫簡單好懂
→ Ghamu: 的程式碼嗎？ 簡單應該是常態 複雜是非常泰吧？
可惜隨著功能愈來愈強大，程式碼自然就愈趨複雜。
把複雜的 module，拆分成獨立 tiny module，每個 module 都變得精簡，
這樣增加了可讀性、重複利用性、可維護性，是工程師該做的。
但其實沒有把 code 變得簡單，只是把一個 function 能做的事，
變成一堆 function 合起來作。

當我一個 function 裡面 call 了 100 個其它的 function；
或者 function flow 拉得很長，跨越了 100 個 function。
也許我每個 function 都通俗易懂一目瞭然，不用註解，
但還是得花時間看完這些 code 才懂這 100 個 function 合起來是在幹嘛。

而這個時間，也許只要兩行註解就可以代替。

想像一個具有 100 個 event 的 event sysem，
event 間另有交互合作及互斥關係，
也許每一個 event 都只用了兩三行 code，一看就明白，
所以不需要註解這個 event 在幹嘛。
但其它的人，光是要找到其中一個 event 就很花時間，
更不用說這個 event 牽涉到其它的哪些 event。

function event1_handler()
{
  code line 1...
  code line 2...
}

這樣超簡單的 event，不用註解嗎？

我覺得要，註解可能會長這樣

// event 1 affects
// - event 22
// - event 36
// - event 47
// - ...
// and NOT used concurrently with
// - event 7
// - event 71

但類似這種註解會需要花很多時間維護，
所以我個人會建議記錄成一張表格就好。

→ RapidGrowth: 其實還是有else, 只是被當default case, 我認為這樣
→ RapidGrowth: 還是不嚴謹的
※ 編輯: babelism (59.127.94.119), 12/29/2018 11:20:08
推 philip80220: 推
→ RapidGrowth: 沒有看前篇文章就回了
→ RapidGrowth: 我的看法跟前篇文章是比較相似的。前篇他那種寫法只
→ RapidGrowth: 是視覺上難看，其實邏輯上是比較清晰的，非常嚴謹，
→ RapidGrowth: 真的產品要夠stable的話，這些是避不掉的。雖然我覺
→ RapidGrowth: 得有可以深層套嵌的寫法，但並不是簡單的不處理else
→ RapidGrowth: 分支。
→ RapidGrowth: 更正：有可以避開深層套嵌的寫法
推 kyrie77: 推這篇
→ rofellosx: 我比較討厭各家語言簡潔if寫法..