轉自推特
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/

第二張 XD

login(para) //login method

tricky的要吧?

貓貓可愛

以前覺得是笑話 真正遇到之後發現我自己才是笑話...兩千多行的遞迴FOR循環 註解寫//循環讀資料 幹你娘

XDDDDDDDDD

認同

#define ZERO 0 //origin

註解都是在罵老闆、表同事

最好的code本身應該要解釋它自己，很多註解很容易寫廢話

真的 看到self-explanatory code效率高很多

Code 只能解釋 what 註解跟文檔可也解釋 why

本文有提到不要盡相信code即是註解 就是因為沒有那麼多最好的code阿XD能在註解多給可能有用的資訊 對後面接手的人都是有幫助的

我同意沒那麼多"最好"的code，但這是可以改進的方向

可是一堆人寫的code就是讓人看不懂阿 阿對了 有些人英文不太好 寫了註解也是讓人沒看懂

//下班前突然來一顆隕石，所以這樣寫才能正常下班

謝謝分享

code 可以自己解釋在做什麼 註解用來解釋為什麼要這樣做cra 的註解就很棒 https://tinyurl.com/2w6wd9re

安心しろ！老闆要是刻意挑刺，無論註解解釋的再清楚總是會有意見的。只是清楚的註解讓後面接手能短痛接手，就寫進linked inprofile裏面，當做自己的credit。

同意，很多code需求都要寫清楚，沒有註解靠通靈

//不知道為什麼加了這行才能動

對不起 我也這樣寫...QQ

//Google到的，我也不知道為什麼

// for test結果那行拿掉就掛了…明明是必要的啊！為何要寫for test....

貓咪<3

// something to do

有看過解釋來龍去脈很多行但如同沒講的狀況嗎？ 個人還是習慣Keep it simple and flexible

我覺得註解可以寫這程式用在哪裡，比寫他在幹嘛好，程式在幹嘛應該表現在命名上

//shit code

用在哪與在做什麼很容易寫的差不多 命名也要看長度駝峰命名太長會很悲劇 唯一支持_不過已有的系統就沒辦法了 全小寫+下劃線非常清爽 眼球無壓力

if {...} // end of if

同意，推這篇

看過最實用註解是 // 千萬別在這函式前 aquire mutex

//stackoverflow的連結

同意，謝分享

需要撇清責任時會寫，某年某月某董要求修改之類的

// Wtf is this? stubbed.

//我先走了 剩下交給你了

//看不懂 塊陶啊

認同

// here could be a bug

// Pasted from web. Idk why it works.

// 幹你老師好想下班

//SNIS-OOO

// just workaround

// 垃圾欺負新人的 senior 都去死

樓上怎麼了??

我看過想一套, 寫一套, 註解一套, 每套不一樣還分版本.最好玩的是程式跑起來還沒問題...

推

沒有我留錯地方了哈哈哈

我抱怨需求都是寫在 commit 裡

哪天幹得不爽，在離職走人前將重要的code全註解掉。（誤BTW，整串的怨念感覺深不見底，之前看過TechLead的影片也許能參考下，網址在此：https://ptt.cc/fXESYx不然去YT搜" anti-patterns techlead"就找得到了。這招註解還狠…

linux kernel有一行程式配五十行註解說不用lock的原因靠腰按錯碰到噓，等等補推補推

是不要相信註解即是code吧 code本來就是絕對存在的 code才是真正在run的 註解並不靠譜

// 我在絕情谷底 嗡嗡嗡

如果你有寫過go的code你就不會這樣說了，光是變數明名跟func動名詞，就可以寫完詳細的說明文件，然後加上func的標記註解及一個README.md就整份文件寫完收工

我看你是沒看過兩個go channel互相咬住 要寫註解警告接手者不要在一個channel返回前往另一個channel塞值

我覺得適度可以，但多半是大公司內被轉了不知道幾手的Code中間改的人不見得有維護註解，也不是人人都有能力寫好讓人可以理解用途的Code，更該是個相輔相成的東西

看過寫//獨立 的...

// 不寫不能下班

code只能解釋做了什麼 但無法解釋為什麼這麼做把意圖、Why要寫在註解裡面，常常幫助到的是未來的自己

#不知道為什麼不能用//當註解,所以就改成#針對markbex大大的需求,版控summery更加的適合

提到golang直接看標準庫https://golang.org/pkg/net/註解寫非常多而且詳細有誰可以只用code表達所有事物的人我只能說你厲害喔

光看Code不看註解就知道這段Code是作啥，那也很強大。

只看code可以理解他做啥 厲害的不是看得人 是寫的人不相信註解不是因為能不能寫的詳細 是因為通常會忘了維護

註解的問題是有可能誤導 有維護性的問題 就算它寫的時候是ok的 但後來code變更時註解是否也同時更新?註解跟code不一樣時還不是得看code

//Magic number

樓上提到維護性的問題 code本身也有阿 什麼東西不好好維護都會遇到問題 這種情況有問題的都是人 不是這工具

//更多更詳盡程式碼 在Stack Overflowcode是本體 註解是輔助讓code更完善 彼此相輔相成

這個所說的維護性問題應該是說一致性問題 code沒有一致性問題 不管寫得再爛 它跟實際上run的是完全一致因為一致性問題 所以註解要隨時維護得跟code一樣

註解麻煩在維護 當然可以說我看code最準哪需要管註解但不一致時你不知道是code寫錯了 還是註解沒更新…

這就是註解麻煩的一面 容易誤導 基本上code"不會錯"註解可以無視 code 就是現在run起來的樣子 如果不對不符合需求 就改code註解跟code不一致時 基本上你根本不要管註解 因為註解通常是更新度比不上code 你要做的只是把code run一遍 看看是不是符合預期 在意註解變成它在混淆你所以說為什麼註解最好只解釋架構或者作者的意圖 不要去寫太過細節的東西 因為架構跟意圖通常不容易隨時間而改變 要把註解的其它功能 放在把code寫得清楚易懂上面 清楚易懂的code本身就是一種註解

更多的是覺得自己寫得很好所以不用加註解

像我公司都直接不註解的 註解還會被嗆，看 code 就不好

哈 還有遇過會刪註解的 XDDDDD

註解就是用來//WORKAROUND:XXX //TODO:XXX //FXCK:XXX用來解釋給後面維護的人知道原因 以面被罵 那個廢物前輩寫這什麼鬼扣以免

The code is right there, we know what it does. 英語這兩句講得很好 都講完了

// TODO

註解好好寫啦 對你自己好不要哪天你回來看你自己的code都看不懂

推樓上

你的code功能太簡單才能光靠code表達 常常一些code都是為了某個special case存在的 不靠註解誰知道用意當然也可以靠commit講啦 但對讀的人來說就是麻煩在那邊說好的code不需要註解的 往往只是給自己的懶惰找藉口