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

[alihue (wanda wanda)]

轉自推特

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
推 cuteSquirrel: 第二張 XD
推 becca945: https://i.imgur.com/4AxoGNi.png
$array = array(); // array
※ 編輯: alihue (106.73.26.66 日本), 03/19/2021 22:58:58
推 neo5277: login(para) //login method
推 clamperni: tricky的要吧?
推 cuteSquirrel: 貓貓可愛
→ spfy: 以前覺得是笑話 真正遇到之後發現我自己才是笑話...
→ spfy: 兩千多行的遞迴FOR循環 註解寫//循環讀資料 幹你娘
推 cuteSquirrel: XDDDDDDDDD
推 drajan: 認同
推 chuegou: #define ZERO 0 //origin
推 ctrlbreak: 註解都是在罵老闆、表同事
推 Sixigma: 最好的code本身應該要解釋它自己，很多註解很容易寫廢話
推 cuteSquirrel: 真的 看到self-explanatory code效率高很多
推 drajan: Code 只能解釋 what 註解跟文檔可也解釋 why
推 pikaka: 本文有提到不要盡相信code即是註解 就是因為
→ pikaka: 沒有那麼多最好的code阿XD
→ pikaka: 能在註解多給可能有用的資訊 對後面接手的人都是有幫助的
推 Sixigma: 我同意沒那麼多"最好"的code，但這是可以改進的方向
→ wawi2: 可是一堆人寫的code就是讓人看不懂阿  阿對了  有些人英文
→ wawi2: 不太好  寫了註解也是讓人沒看懂
推 anandydy529: //下班前突然來一顆隕石，所以這樣寫才能正常下班
推 t22251974: 謝謝分享
→ VdustR: code 可以自己解釋在做什麼 註解用來解釋為什麼要這樣做
→ VdustR: cra 的註解就很棒 https://tinyurl.com/2w6wd9re
→ jobintan: 安心しろ！老闆要是刻意挑刺，無論註解解釋的再清楚總是
→ jobintan: 會有意見的。
→ jobintan: 只是清楚的註解讓後面接手能短痛接手，就寫進linked in
→ jobintan:  profile裏面，當做自己的credit。
推 aidansky0989: 同意，很多code需求都要寫清楚，沒有註解靠通靈
推 hduek153: //不知道為什麼加了這行才能動
→ OrzOGC: 對不起 我也這樣寫...QQ
推 mathrew: //Google到的，我也不知道為什麼
推 v7q4: // for test
→ v7q4: 結果那行拿掉就掛了…明明是必要的啊！為何要寫for test....
推 ssd860505da: 貓咪<3
推 stupid0319: // something to do
→ superpandal: 有看過解釋來龍去脈很多行但如同沒講的狀況嗎？ 個人
→ superpandal: 還是習慣Keep it simple and flexible
→ leo5916267: 我覺得註解可以寫這程式用在哪裡，比寫他在幹嘛好，
→ leo5916267: 程式在幹嘛應該表現在命名上
推 t19960804: //shit code
→ superpandal: 用在哪與在做什麼很容易寫的差不多 命名也要看長度
→ superpandal: 駝峰命名太長會很悲劇 唯一支持_
→ superpandal: 不過已有的系統就沒辦法了 全小寫+下劃線非常清爽 眼
→ superpandal: 球無壓力
推 bronx0807: if {...} // end of if
推 howard50009: 同意，推這篇
推 lturtsamuel: 看過最實用註解是 // 千萬別在這函式前 aquire mutex
→ energyy1104: //stackoverflow的連結
推 shibin: 同意，謝分享
推 SKII588: 需要撇清責任時會寫，某年某月某董要求修改之類的
推 CarpeDiemAL: // Wtf is this? stubbed.
推 molopo: //我先走了 剩下交給你了
→ Csongs: //看不懂 塊陶啊
推 WaterLengend: 認同
推 foodordertw: // here could be a bug
推 lee457088: // Pasted from web. Idk why it works.
推 Nigger5566: // 幹你老師好想下班
推 leftless: //SNIS-OOO
推 cuteSquirrel: // just workaround
噓 online135: // 垃圾欺負新人的 senior 都去死
→ WunoW: 樓上怎麼了??
推 Muscovy: 我看過想一套, 寫一套, 註解一套, 每套不一樣還分版本.
→ Muscovy: 最好玩的是程式跑起來還沒問題...
推 hamster3933: 推
→ online135: 沒有我留錯地方了哈哈哈
推 v7q4: http://i.imgur.com/b5mI5Kh.jpg
推 abc0922001: 我抱怨需求都是寫在 commit 裡
→ jobintan: 哪天幹得不爽，在離職走人前將重要的code全註解掉。（誤
→ jobintan: BTW，整串的怨念感覺深不見底，之前看過TechLead的影片
→ jobintan: 也許能參考下，網址在此：
→ jobintan: https://ptt.cc/fXESYx
→ jobintan: 不然去YT搜" anti-patterns techlead"就找得到了。
→ jobintan: 這招註解還狠…
噓 wulouise: linux kernel有一行程式配五十行註解說不用lock的原因
→ wulouise: 靠腰按錯碰到噓，等等補推
推 wulouise: 補推
噓 jamesho8743: 是不要相信註解即是code吧 code本來就是絕對存在的 c
→ jamesho8743: ode才是真正在run的 註解並不靠譜
推 jej: // 我在絕情谷底 嗡嗡嗡
推 marc47: 如果你有寫過go的code你就不會這樣說了，光是變數明名跟fu
→ marc47: nc動名詞，就可以寫完詳細的說明文件，然後加上func的標記
→ marc47: 註解及一個README.md就整份文件寫完收工
推 lturtsamuel: 我看你是沒看過兩個go channel互相咬住 要寫註解警告
→ lturtsamuel: 接手者不要在一個channel返回前往另一個channel塞值
推 twonia: 我覺得適度可以，但多半是大公司內被轉了不知道幾手的Code
→ twonia: 中間改的人不見得有維護註解，也不是人人都有能力寫好讓人
→ twonia: 可以理解用途的Code，更該是個相輔相成的東西
推 azureroki: 看過寫//獨立 的...
→ ketrobo: // 不寫不能下班
推 markbex: code只能解釋做了什麼 但無法解釋為什麼這麼做
→ markbex: 把意圖、Why要寫在註解裡面，常常幫助到的是未來的自己
→ leolarrel: #不知道為什麼不能用//當註解,所以就改成#
→ leolarrel: 針對markbex大大的需求,版控summery更加的適合
→ MoonCode: 提到golang直接看標準庫
→ MoonCode: https://golang.org/pkg/net/
→ MoonCode: 註解寫非常多而且詳細
→ MoonCode: 有誰可以只用code表達所有事物的人我只能說你厲害喔
→ jobintan: 光看Code不看註解就知道這段Code是作啥，那也很強大。
→ shooter555: 只看code可以理解他做啥 厲害的不是看得人 是寫的人
→ shooter555: 不相信註解不是因為能不能寫的詳細 是因為通常會忘了
→ shooter555: 維護
噓 jamesho8743: 註解的問題是有可能誤導 有維護性的問題 就算它寫的
→ jamesho8743: 時候是ok的 但後來code變更時註解是否也同時更新?
→ jamesho8743:  註解跟code不一樣時還不是得看code
推 lwecloud: //Magic number
→ pikaka: 樓上提到維護性的問題 code本身也有阿 什麼東西不好好維護
→ pikaka: 都會遇到問題 這種情況有問題的都是人 不是這工具
推 s0914714: //更多更詳盡程式碼 在Stack Overflow
→ s0914714: code是本體 註解是輔助讓code更完善 彼此相輔相成
推 jamesho8743: 這個所說的維護性問題應該是說一致性問題 code沒有一
→ jamesho8743: 致性問題 不管寫得再爛 它跟實際上run的是完全一致
→ jamesho8743: 因為一致性問題 所以註解要隨時維護得跟code一樣
→ cha122977: 註解麻煩在維護 當然可以說我看code最準哪需要管註解
→ cha122977: 但不一致時你不知道是code寫錯了 還是註解沒更新…
噓 jamesho8743: 這就是註解麻煩的一面 容易誤導 基本上code"不會錯"
→ jamesho8743:  註解可以無視 code 就是現在run起來的樣子 如果不
→ jamesho8743: 對不符合需求 就改code
→ jamesho8743: 註解跟code不一致時 基本上你根本不要管註解 因為註
→ jamesho8743: 解通常是更新度比不上code 你要做的只是把code run
→ jamesho8743:  一遍 看看是不是符合預期 在意註解變成它在混淆你
推 jamesho8743: 所以說為什麼註解最好只解釋架構或者作者的意圖 不要
→ jamesho8743: 去寫太過細節的東西 因為架構跟意圖通常不容易隨時
→ jamesho8743: 間而改變 要把註解的其它功能 放在把code寫得清楚易
→ jamesho8743: 懂上面 清楚易懂的code本身就是一種註解
→ yyc1217: 更多的是覺得自己寫得很好所以不用加註解
推 b85040312: 像我公司都直接不註解的 註解還會被嗆，看 code 就不好
推 cuteSquirrel: 哈 還有遇過會刪註解的 XDDDDD
→ shooter555: 註解就是用來//WORKAROUND:XXX //TODO:XXX //FXCK:XXX
→ shooter555: 用來解釋給後面維護的人知道原因 以面被罵 那個廢物前
→ shooter555: 輩寫這什麼鬼扣
→ shooter555:                                以免
推 jamesho8743: The code is right there, we know what it does. 英
→ jamesho8743: 語這兩句講得很好 都講完了
→ mrnegativetw: // TODO
推 mmppeegg: 註解好好寫啦 對你自己好
→ mmppeegg: 不要哪天你回來看你自己的code都看不懂
→ viper9709: 推樓上
→ BoXeX: 你的code功能太簡單才能光靠code表達   常常一些code都是
→ BoXeX: 為了某個special case存在的   不靠註解誰知道用意
→ BoXeX: 當然也可以靠commit講啦   但對讀的人來說就是麻煩
→ BoXeX: 在那邊說好的code不需要註解的   往往只是給自己的懶惰找
→ BoXeX: 藉口
推 molopo: 拜託不寫註解 亂命名的 獨立接案就好 不要出來害人好嗎