作者alihue (wanda wanda)
看板Soft_Job
標題[心得] 好的註解是解釋為何需要這段 code
時間Fri Mar 19 22:35:42 2021
轉自推特
https://twitter.com/BenLesh/status/1372562839475470336?s=20
Add comments about WHY code exists, not what it does.
The code is right there, we know what it does.
註解應該用來解釋這段 code 的背景需求/含意，
而不是把 code 表面上的意思再講一次
ps. 推特內有範例圖
https://i.imgur.com/fNQakeb.jpg
還有 不要盡相信 code 即是註解，
有時給你開 debug mode 你還是不曉得為何要這樣幹
ps. 版上比較少轉貼型文章，試水溫。reddit 蠻流行只貼鏈結的
https://www.reddit.com/r/programming/
--
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 106.73.26.66 (日本)
※ 文章網址: https://webptt.com/m.aspx?n=bbs/Soft_Job/M.1616164544.A.66E.html
※ 編輯: alihue (106.73.26.66 日本), 03/19/2021 22:37:36
1F：推 cuteSquirrel: 第二張 XD 03/19 22:40
$array = array(); // array
※ 編輯: alihue (106.73.26.66 日本), 03/19/2021 22:58:58
3F：推 neo5277: login(para) //login method 03/19 23:17
4F：推 clamperni: tricky的要吧? 03/19 23:24
5F：推 cuteSquirrel: 貓貓可愛 03/19 23:49
6F：→ spfy: 以前覺得是笑話 真正遇到之後發現我自己才是笑話... 03/19 23:54
7F：→ spfy: 兩千多行的遞迴FOR循環 註解寫//循環讀資料 幹你娘 03/19 23:56
8F：推 cuteSquirrel: XDDDDDDDDD 03/19 23:57
9F：推 drajan: 認同 03/20 00:00
10F：推 chuegou: #define ZERO 0 //origin 03/20 00:09
11F：推 ctrlbreak: 註解都是在罵老闆、表同事 03/20 00:10
12F：推 Sixigma: 最好的code本身應該要解釋它自己，很多註解很容易寫廢話 03/20 00:34
13F：推 cuteSquirrel: 真的 看到self-explanatory code效率高很多 03/20 00:36
14F：推 drajan: Code 只能解釋 what 註解跟文檔可也解釋 why 03/20 00:37
15F：推 pikaka: 本文有提到不要盡相信code即是註解 就是因為 03/20 00:51
16F：→ pikaka: 沒有那麼多最好的code阿XD 03/20 00:51
17F：→ pikaka: 能在註解多給可能有用的資訊 對後面接手的人都是有幫助的 03/20 00:57
18F：推 Sixigma: 我同意沒那麼多"最好"的code，但這是可以改進的方向 03/20 01:10
19F：→ wawi2: 可是一堆人寫的code就是讓人看不懂阿 阿對了 有些人英文 03/20 01:22
20F：→ wawi2: 不太好 寫了註解也是讓人沒看懂 03/20 01:22
21F：推 anandydy529: //下班前突然來一顆隕石，所以這樣寫才能正常下班 03/20 02:26
22F：推 t22251974: 謝謝分享 03/20 02:34
23F：→ VdustR: code 可以自己解釋在做什麼 註解用來解釋為什麼要這樣做 03/20 04:18
25F：→ jobintan: 安心しろ！老闆要是刻意挑刺，無論註解解釋的再清楚總是 03/20 06:52
26F：→ jobintan: 會有意見的。 03/20 06:53
27F：→ jobintan: 只是清楚的註解讓後面接手能短痛接手，就寫進linked in 03/20 06:55
28F：→ jobintan: profile裏面，當做自己的credit。 03/20 06:55
29F：推 aidansky0989: 同意，很多code需求都要寫清楚，沒有註解靠通靈 03/20 08:14
30F：推 hduek153: //不知道為什麼加了這行才能動 03/20 08:50
31F：→ OrzOGC: 對不起 我也這樣寫...QQ 03/20 08:56
32F：推 mathrew: //Google到的，我也不知道為什麼 03/20 09:08
33F：推 v7q4: // for test 03/20 09:45
34F：→ v7q4: 結果那行拿掉就掛了…明明是必要的啊！為何要寫for test.... 03/20 09:46
35F：推 ssd860505da: 貓咪<3 03/20 09:55
36F：推 stupid0319: // something to do 03/20 10:21
37F：→ superpandal: 有看過解釋來龍去脈很多行但如同沒講的狀況嗎？ 個人 03/20 10:31
38F：→ superpandal: 還是習慣Keep it simple and flexible 03/20 10:32
39F：→ leo5916267: 我覺得註解可以寫這程式用在哪裡，比寫他在幹嘛好， 03/20 10:45
40F：→ leo5916267: 程式在幹嘛應該表現在命名上 03/20 10:45
41F：推 t19960804: //shit code 03/20 10:48
42F：→ superpandal: 用在哪與在做什麼很容易寫的差不多 命名也要看長度 03/20 10:53
43F：→ superpandal: 駝峰命名太長會很悲劇 唯一支持_ 03/20 10:54
44F：→ superpandal: 不過已有的系統就沒辦法了 全小寫+下劃線非常清爽 眼 03/20 11:00
45F：→ superpandal: 球無壓力 03/20 11:00
46F：推 bronx0807: if {...} // end of if 03/20 11:03
47F：推 howard50009: 同意，推這篇 03/20 11:17
48F：推 lturtsamuel: 看過最實用註解是 // 千萬別在這函式前 aquire mutex 03/20 11:42
49F：→ energyy1104: //stackoverflow的連結 03/20 11:48
50F：推 shibin: 同意，謝分享 03/20 12:07
51F：推 SKII588: 需要撇清責任時會寫，某年某月某董要求修改之類的 03/20 12:08
52F：推 CarpeDiemAL: // Wtf is this? stubbed. 03/20 12:35
53F：推 molopo: //我先走了 剩下交給你了 03/20 12:56
54F：→ Csongs: //看不懂 塊陶啊 03/20 12:57
55F：推 WaterLengend: 認同 03/20 12:59
56F：推 foodordertw: // here could be a bug 03/20 13:33
57F：推 lee457088: // Pasted from web. Idk why it works. 03/20 13:39
58F：推 Nigger5566: // 幹你老師好想下班 03/20 13:58
59F：推 leftless: //SNIS-OOO 03/20 14:47
60F：推 cuteSquirrel: // just workaround 03/20 15:03
61F：噓 online135: // 垃圾欺負新人的 senior 都去死 03/20 15:51
62F：→ WunoW: 樓上怎麼了?? 03/20 16:06
63F：推 Muscovy: 我看過想一套, 寫一套, 註解一套, 每套不一樣還分版本. 03/20 16:18
64F：→ Muscovy: 最好玩的是程式跑起來還沒問題... 03/20 16:19
65F：推 hamster3933: 推 03/20 16:50
66F：→ online135: 沒有我留錯地方了哈哈哈 03/20 17:52
68F：推 abc0922001: 我抱怨需求都是寫在 commit 裡 03/20 18:47
69F：→ jobintan: 哪天幹得不爽，在離職走人前將重要的code全註解掉。（誤 03/20 19:51
70F：→ jobintan: BTW，整串的怨念感覺深不見底，之前看過TechLead的影片 03/20 19:54
71F：→ jobintan: 也許能參考下，網址在此： 03/20 19:55
73F：→ jobintan: 不然去YT搜" anti-patterns techlead"就找得到了。 03/20 19:59
74F：→ jobintan: 這招註解還狠… 03/20 20:00
75F：噓 wulouise: linux kernel有一行程式配五十行註解說不用lock的原因 03/20 21:37
76F：→ wulouise: 靠腰按錯碰到噓，等等補推 03/20 21:37
77F：推 wulouise: 補推 03/20 21:45
78F：噓 jamesho8743: 是不要相信註解即是code吧 code本來就是絕對存在的 c 03/20 22:13
79F：→ jamesho8743: ode才是真正在run的 註解並不靠譜 03/20 22:13
80F：推 jej: // 我在絕情谷底 嗡嗡嗡 03/20 23:13
81F：推 marc47: 如果你有寫過go的code你就不會這樣說了，光是變數明名跟fu 03/21 01:06
82F：→ marc47: nc動名詞，就可以寫完詳細的說明文件，然後加上func的標記 03/21 01:06
83F：→ marc47: 註解及一個README.md就整份文件寫完收工 03/21 01:06
84F：推 lturtsamuel: 我看你是沒看過兩個go channel互相咬住 要寫註解警告 03/21 01:44
85F：→ lturtsamuel: 接手者不要在一個channel返回前往另一個channel塞值 03/21 01:44
86F：推 twonia: 我覺得適度可以，但多半是大公司內被轉了不知道幾手的Code 03/21 08:16
87F：→ twonia: 中間改的人不見得有維護註解，也不是人人都有能力寫好讓人 03/21 08:16
88F：→ twonia: 可以理解用途的Code，更該是個相輔相成的東西 03/21 08:16
89F：推 azureroki: 看過寫//獨立 的... 03/21 08:30
90F：→ ketrobo: // 不寫不能下班 03/21 10:15
91F：推 markbex: code只能解釋做了什麼 但無法解釋為什麼這麼做 03/21 14:15
92F：→ markbex: 把意圖、Why要寫在註解裡面，常常幫助到的是未來的自己 03/21 14:15
93F：→ leolarrel: #不知道為什麼不能用//當註解,所以就改成# 03/22 10:33
94F：→ leolarrel: 針對markbex大大的需求,版控summery更加的適合 03/22 10:34
95F：→ MoonCode: 提到golang直接看標準庫 03/22 12:13
97F：→ MoonCode: 註解寫非常多而且詳細 03/22 12:13
98F：→ MoonCode: 有誰可以只用code表達所有事物的人我只能說你厲害喔 03/22 12:14
99F：→ jobintan: 光看Code不看註解就知道這段Code是作啥，那也很強大。 03/22 12:25
100F：→ shooter555: 只看code可以理解他做啥 厲害的不是看得人 是寫的人 03/22 13:47
101F：→ shooter555: 不相信註解不是因為能不能寫的詳細 是因為通常會忘了 03/22 14:02
102F：→ shooter555: 維護 03/22 14:02
103F：噓 jamesho8743: 註解的問題是有可能誤導 有維護性的問題 就算它寫的 03/22 16:02
104F：→ jamesho8743: 時候是ok的 但後來code變更時註解是否也同時更新? 03/22 16:02
105F：→ jamesho8743: 註解跟code不一樣時還不是得看code 03/22 16:02
106F：推 lwecloud: //Magic number 03/22 16:56
107F：→ pikaka: 樓上提到維護性的問題 code本身也有阿 什麼東西不好好維護 03/22 19:22
108F：→ pikaka: 都會遇到問題 這種情況有問題的都是人 不是這工具 03/22 19:22
109F：推 s0914714: //更多更詳盡程式碼 在Stack Overflow 03/23 01:08
110F：→ s0914714: code是本體 註解是輔助讓code更完善 彼此相輔相成 03/23 01:11
111F：推 jamesho8743: 這個所說的維護性問題應該是說一致性問題 code沒有一 03/23 08:31
112F：→ jamesho8743: 致性問題 不管寫得再爛 它跟實際上run的是完全一致 03/23 08:31
113F：→ jamesho8743: 因為一致性問題 所以註解要隨時維護得跟code一樣 03/23 08:33
114F：→ cha122977: 註解麻煩在維護 當然可以說我看code最準哪需要管註解 03/23 09:04
115F：→ cha122977: 但不一致時你不知道是code寫錯了 還是註解沒更新… 03/23 09:05
116F：噓 jamesho8743: 這就是註解麻煩的一面 容易誤導 基本上code"不會錯" 03/23 20:44
117F：→ jamesho8743: 註解可以無視 code 就是現在run起來的樣子 如果不 03/23 20:44
118F：→ jamesho8743: 對不符合需求 就改code 03/23 20:44
119F：→ jamesho8743: 註解跟code不一致時 基本上你根本不要管註解 因為註 03/23 20:49
120F：→ jamesho8743: 解通常是更新度比不上code 你要做的只是把code run 03/23 20:49
121F：→ jamesho8743: 一遍 看看是不是符合預期 在意註解變成它在混淆你 03/23 20:49
122F：推 jamesho8743: 所以說為什麼註解最好只解釋架構或者作者的意圖 不要 03/23 20:54
123F：→ jamesho8743: 去寫太過細節的東西 因為架構跟意圖通常不容易隨時 03/23 20:54
124F：→ jamesho8743: 間而改變 要把註解的其它功能 放在把code寫得清楚易 03/23 20:54
125F：→ jamesho8743: 懂上面 清楚易懂的code本身就是一種註解 03/23 20:54
126F：→ yyc1217: 更多的是覺得自己寫得很好所以不用加註解 03/23 21:08
127F：推 b85040312: 像我公司都直接不註解的 註解還會被嗆，看 code 就不好 03/23 21:17
128F：推 cuteSquirrel: 哈 還有遇過會刪註解的 XDDDDD 03/24 12:03
129F：→ shooter555: 註解就是用來//WORKAROUND:XXX //TODO:XXX //FXCK:XXX 03/24 13:04
130F：→ shooter555: 用來解釋給後面維護的人知道原因 以面被罵 那個廢物前 03/24 13:07
131F：→ shooter555: 輩寫這什麼鬼扣 03/24 13:07
132F：→ shooter555: 以免 03/24 13:08
133F：推 jamesho8743: The code is right there, we know what it does. 英 03/24 18:19
134F：→ jamesho8743: 語這兩句講得很好 都講完了 03/24 18:19
135F：→ mrnegativetw: // TODO 03/25 18:48
136F：推 mmppeegg: 註解好好寫啦 對你自己好 03/29 14:30
137F：→ mmppeegg: 不要哪天你回來看你自己的code都看不懂 03/29 14:30
138F：→ viper9709: 推樓上 03/29 23:56
139F：→ BoXeX: 你的code功能太簡單才能光靠code表達 常常一些code都是 04/01 15:14
140F：→ BoXeX: 為了某個special case存在的 不靠註解誰知道用意 04/01 15:14
141F：→ BoXeX: 當然也可以靠commit講啦 但對讀的人來說就是麻煩 04/01 15:14
142F：→ BoXeX: 在那邊說好的code不需要註解的 往往只是給自己的懶惰找 04/01 15:16
143F：→ BoXeX: 藉口 04/01 15:16
144F：推 molopo: 拜託不寫註解 亂命名的 獨立接案就好 不要出來害人好嗎 01/19 12:44