[心得] 好的註解是解釋為何需要這段 code

看板Soft_Job作者 (wanda wanda)時間3年前 (2021/03/19 22:35), 3年前編輯推噓49(54推 5噓 76→)
留言135則, 61人參與, 3年前最新討論串1/2 (看更多)
轉自推特 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://www.ptt.cc/bbs/Soft_Job/M.1616164544.A.66E.html ※ 編輯: alihue (106.73.26.66 日本), 03/19/2021 22:37:36
推
03/19 22:40, 3年前 , 1F
第二張 XD
03/19 22:40, 1F
推
03/19 22:53, 3年前 , 2F
03/19 22:53, 2F
$array = array(); // array ※ 編輯: alihue (106.73.26.66 日本), 03/19/2021 22:58:58
推
03/19 23:17, 3年前 , 3F
login(para) //login method
03/19 23:17, 3F
推
03/19 23:24, 3年前 , 4F
tricky的要吧?
03/19 23:24, 4F
推
03/19 23:49, 3年前 , 5F
貓貓可愛
03/19 23:49, 5F
→
03/19 23:54, 3年前 , 6F
以前覺得是笑話 真正遇到之後發現我自己才是笑話...
03/19 23:54, 6F
→
03/19 23:56, 3年前 , 7F
兩千多行的遞迴FOR循環 註解寫//循環讀資料 幹你娘
03/19 23:56, 7F
推
03/19 23:57, 3年前 , 8F
XDDDDDDDDD
03/19 23:57, 8F
推
03/20 00:00, 3年前 , 9F
認同
03/20 00:00, 9F
推
03/20 00:09, 3年前 , 10F
#define ZERO 0 //origin
03/20 00:09, 10F
推
03/20 00:10, 3年前 , 11F
註解都是在罵老闆、表同事
03/20 00:10, 11F
推
03/20 00:34, 3年前 , 12F
最好的code本身應該要解釋它自己，很多註解很容易寫廢話
03/20 00:34, 12F
推
03/20 00:36, 3年前 , 13F
真的 看到self-explanatory code效率高很多
03/20 00:36, 13F
推
03/20 00:37, 3年前 , 14F
Code 只能解釋 what 註解跟文檔可也解釋 why
03/20 00:37, 14F
推
03/20 00:51, 3年前 , 15F
本文有提到不要盡相信code即是註解 就是因為
03/20 00:51, 15F
→
03/20 00:51, 3年前 , 16F
沒有那麼多最好的code阿XD
03/20 00:51, 16F
→
03/20 00:57, 3年前 , 17F
能在註解多給可能有用的資訊 對後面接手的人都是有幫助的
03/20 00:57, 17F
推
03/20 01:10, 3年前 , 18F
我同意沒那麼多"最好"的code，但這是可以改進的方向
03/20 01:10, 18F
→
03/20 01:22, 3年前 , 19F
可是一堆人寫的code就是讓人看不懂阿 阿對了 有些人英文
03/20 01:22, 19F
→
03/20 01:22, 3年前 , 20F
不太好 寫了註解也是讓人沒看懂
03/20 01:22, 20F
推
03/20 02:26, 3年前 , 21F
//下班前突然來一顆隕石，所以這樣寫才能正常下班
03/20 02:26, 21F
推
03/20 02:34, 3年前 , 22F
謝謝分享
03/20 02:34, 22F
→
03/20 04:18, 3年前 , 23F
code 可以自己解釋在做什麼 註解用來解釋為什麼要這樣做
03/20 04:18, 23F
→
03/20 04:20, 3年前 , 24F
cra 的註解就很棒 https://tinyurl.com/2w6wd9re
03/20 04:20, 24F
→
03/20 06:52, 3年前 , 25F
安心しろ！老闆要是刻意挑刺，無論註解解釋的再清楚總是
03/20 06:52, 25F
→
03/20 06:53, 3年前 , 26F
會有意見的。
03/20 06:53, 26F
→
03/20 06:55, 3年前 , 27F
只是清楚的註解讓後面接手能短痛接手，就寫進linked in
03/20 06:55, 27F
→
03/20 06:55, 3年前 , 28F
profile裏面，當做自己的credit。
03/20 06:55, 28F
推
03/20 08:14, 3年前 , 29F
同意，很多code需求都要寫清楚，沒有註解靠通靈
03/20 08:14, 29F
推
03/20 08:50, 3年前 , 30F
//不知道為什麼加了這行才能動
03/20 08:50, 30F
→
03/20 08:56, 3年前 , 31F
對不起 我也這樣寫...QQ
03/20 08:56, 31F
推
03/20 09:08, 3年前 , 32F
//Google到的，我也不知道為什麼
03/20 09:08, 32F
推
03/20 09:45, 3年前 , 33F
// for test
03/20 09:45, 33F
→
03/20 09:46, 3年前 , 34F
結果那行拿掉就掛了…明明是必要的啊！為何要寫for test....
03/20 09:46, 34F
推
03/20 09:55, 3年前 , 35F
貓咪<3
03/20 09:55, 35F
推
03/20 10:21, 3年前 , 36F
// something to do
03/20 10:21, 36F
→
03/20 10:31, 3年前 , 37F
有看過解釋來龍去脈很多行但如同沒講的狀況嗎？ 個人
03/20 10:31, 37F
→
03/20 10:32, 3年前 , 38F
還是習慣Keep it simple and flexible
03/20 10:32, 38F
還有 57 則推文
→
03/22 12:13, 3年前 , 96F
03/22 12:13, 96F
→
03/22 12:13, 3年前 , 97F
註解寫非常多而且詳細
03/22 12:13, 97F
→
03/22 12:14, 3年前 , 98F
有誰可以只用code表達所有事物的人我只能說你厲害喔
03/22 12:14, 98F
→
03/22 12:25, 3年前 , 99F
光看Code不看註解就知道這段Code是作啥，那也很強大。
03/22 12:25, 99F
→
03/22 13:47, 3年前 , 100F
只看code可以理解他做啥 厲害的不是看得人 是寫的人
03/22 13:47, 100F
→
03/22 14:02, 3年前 , 101F
不相信註解不是因為能不能寫的詳細 是因為通常會忘了
03/22 14:02, 101F
→
03/22 14:02, 3年前 , 102F
維護
03/22 14:02, 102F
噓
03/22 16:02, 3年前 , 103F
註解的問題是有可能誤導 有維護性的問題 就算它寫的
03/22 16:02, 103F
→
03/22 16:02, 3年前 , 104F
時候是ok的 但後來code變更時註解是否也同時更新?
03/22 16:02, 104F
→
03/22 16:02, 3年前 , 105F
註解跟code不一樣時還不是得看code
03/22 16:02, 105F
推
03/22 16:56, 3年前 , 106F
//Magic number
03/22 16:56, 106F
→
03/22 19:22, 3年前 , 107F
樓上提到維護性的問題 code本身也有阿 什麼東西不好好維護
03/22 19:22, 107F
→
03/22 19:22, 3年前 , 108F
都會遇到問題 這種情況有問題的都是人 不是這工具
03/22 19:22, 108F
推
03/23 01:08, 3年前 , 109F
//更多更詳盡程式碼 在Stack Overflow
03/23 01:08, 109F
→
03/23 01:11, 3年前 , 110F
code是本體 註解是輔助讓code更完善 彼此相輔相成
03/23 01:11, 110F
推
03/23 08:31, 3年前 , 111F
這個所說的維護性問題應該是說一致性問題 code沒有一
03/23 08:31, 111F
→
03/23 08:31, 3年前 , 112F
致性問題 不管寫得再爛 它跟實際上run的是完全一致
03/23 08:31, 112F
→
03/23 08:33, 3年前 , 113F
因為一致性問題 所以註解要隨時維護得跟code一樣
03/23 08:33, 113F
→
03/23 09:04, 3年前 , 114F
註解麻煩在維護 當然可以說我看code最準哪需要管註解
03/23 09:04, 114F
→
03/23 09:05, 3年前 , 115F
但不一致時你不知道是code寫錯了 還是註解沒更新…
03/23 09:05, 115F
噓
03/23 20:44, 3年前 , 116F
這就是註解麻煩的一面 容易誤導 基本上code"不會錯"
03/23 20:44, 116F
→
03/23 20:44, 3年前 , 117F
註解可以無視 code 就是現在run起來的樣子 如果不
03/23 20:44, 117F
→
03/23 20:44, 3年前 , 118F
對不符合需求 就改code
03/23 20:44, 118F
→
03/23 20:49, 3年前 , 119F
註解跟code不一致時 基本上你根本不要管註解 因為註
03/23 20:49, 119F
→
03/23 20:49, 3年前 , 120F
解通常是更新度比不上code 你要做的只是把code run
03/23 20:49, 120F
→
03/23 20:49, 3年前 , 121F
一遍 看看是不是符合預期 在意註解變成它在混淆你
03/23 20:49, 121F
推
03/23 20:54, 3年前 , 122F
所以說為什麼註解最好只解釋架構或者作者的意圖 不要
03/23 20:54, 122F
→
03/23 20:54, 3年前 , 123F
去寫太過細節的東西 因為架構跟意圖通常不容易隨時
03/23 20:54, 123F
→
03/23 20:54, 3年前 , 124F
間而改變 要把註解的其它功能 放在把code寫得清楚易
03/23 20:54, 124F
→
03/23 20:54, 3年前 , 125F
懂上面 清楚易懂的code本身就是一種註解
03/23 20:54, 125F
→
03/23 21:08, 3年前 , 126F
更多的是覺得自己寫得很好所以不用加註解
03/23 21:08, 126F
推
03/23 21:17, 3年前 , 127F
像我公司都直接不註解的 註解還會被嗆，看 code 就不好
03/23 21:17, 127F
推
03/24 12:03, 3年前 , 128F
哈 還有遇過會刪註解的 XDDDDD
03/24 12:03, 128F
→
03/24 13:04, 3年前 , 129F
註解就是用來//WORKAROUND:XXX //TODO:XXX //FXCK:XXX
03/24 13:04, 129F
→
03/24 13:07, 3年前 , 130F
用來解釋給後面維護的人知道原因 以面被罵 那個廢物前
03/24 13:07, 130F
→
03/24 13:07, 3年前 , 131F
輩寫這什麼鬼扣
03/24 13:07, 131F
→
03/24 13:08, 3年前 , 132F
以免
03/24 13:08, 132F
推
03/24 18:19, 3年前 , 133F
The code is right there, we know what it does. 英
03/24 18:19, 133F
→
03/24 18:19, 3年前 , 134F
語這兩句講得很好 都講完了
03/24 18:19, 134F
→
03/25 18:48, 3年前 , 135F
// TODO
03/25 18:48, 135F
‣ 更多 alihue 的文章
文章代碼(AID): #1WLBR0Pk (Soft_Job)
‣ 更多 alihue 的文章
文章代碼(AID): #1WLBR0Pk (Soft_Job)