※ 引述《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 表面上的意思再講一次
上週在重構某段程式碼時，其中一位同事在 code review 中建議把某個註解刪掉，另一
個同事看到這個評論時，在下面留了言說他認為不應該刪掉，於是我們就拉了一個小討論
，聊在程式碼中寫註解這件事。
因為這個經驗，我回去重翻史丹佛電腦科學教授 John Ousterhout 寫的《A Philosophy
of Software Design》一書，並整理了筆記。該教授的觀點是認為程式碼寫註解有很多好
處，但不是任何地方都該寫註解。
在版上找到這篇之前有版大發的文，基本上跟 John Ousterhout 教授的觀點一樣，
就是註解要解釋背後的「為什麼」，而不是把程式碼做的事重複說一次。

推~感謝分享

推 謝謝大大分享

好文推推

沒時間看完整篇文章,這就跟一萬小時變大師的觀點呵呵

推

推 我註解都看心情 然後畫恐龍註解圖 嘻嘻

講的好

推分享~註解本來就該寫這段在做啥,為啥這樣做

推～上次看這本書好久以前了 看完心得整理好像又讀一遍了

我想要知道函式的功能 和為什麼要用無符號整數來存指標QQ

推，meta data那段講的不錯

分享推

感謝分享～

那需求一直變，後續也要持續維護這段註解嗎？

我記憶力很差 我的註解都是為了讓以後維護的我看得懂這段code在寫啥

樓上的狀況我也有,只是我都用git取代註解就是了

回 aid：我自己會註解加說是什麼時候的需求、修改的新邏輯是什麼，程式註解我都會維護

註解是需要維護的，但註解只是輔助工具，理論上不會多到造成負擔，如果會，可能是程式太亂需要大量註解，或是有太多沒必要的註解

我註解只會寫特殊的商業邏輯來輔助程式碼的不足~

推樓上

當文件的一環吧文件要維護，註解當然也要

優文推一個，謝謝分享

註解當然要維護啊，但至少沒維護歷史看得出來

感謝回覆，之前看clean code提到很多寫註解的壞處，像是接手的人不一定會維護註解、註解缺少維護可能會過時、誤導等壞處，後來只有TODO我才會寫註解，寧可後人多跟PM確認新的現狀不然註解寫出來，也不太有人敢修改、刪除可能也是個問題

沒寫註解基本上也不應該隨意修改刪除啊，要做的事情是補測試或是找人釐清需求，再去做變動，註解就是輔助工程師更好做到這些事很多人不寫註解或是不喜歡文件以及測試的理由都是要多維護的工，但往往省略掉這些以後，是花更多的時間開會，或是慢慢變技術債

“不一定會維護“這為啥要算註解的缺點....整個軟體開發一堆東西都有人不維護= =

另外需求一直變並不是不寫註解的理由，不寫就是用人腦記憶，沒紀錄還可能記錯，基本上就是賭這個未爆彈不會炸到你而已

修改刪除是指註解，因為不及時更新註解就會隨需求變動過時，可能造成誤導而非指引

這本書作者的論點跟 foreverk 大說的蠻相近的這位史丹佛教授在書中最開始就提到，他不認同蠻多Clean Code 裡面提到的觀點，但他也不覺得自己的就適合在所有脈絡。所以他的書名是 a philosophy而不是 the philosophy

如果指得是不敢修改或刪除註解，那就代表改code的人並沒有完全掌握這項功能，改善方式應該是增加掌握度，而不是捨棄註解本身

推

假如有好好寫 commit 訊息，再寫個簡單 script 可以過濾時間/檔案/行數/關鍵字/作者 找出相關 commit 也不錯

好的程式不需要註解，你說得都是文件應該要做到的

推

不寫註解很常伴隨著不寫文件，最常見的第二個理由就是認為好程式不需要註解/文件，可是一些特殊商業邏輯所產生的程式，他不好但他是因應當時時空背景而生，這類情況還不寫，那就是上面我說的未爆彈樓上說的commit也是應該要好好寫的一點，甚至應該pr也好好寫，不想維護一整份文件的話，更應該從這些細節去提升程式可維護性

寫註解這種事就是誰當老闆就聽誰的...現實世界就是階級,書再怎麼賣學校再有名都沒用

如果有些重構會搬移程式碼到不同的專案或檔案這時git的紀錄也很難追踨

一個方式是搬家時舊的留著標 deprecated, see also...留個線索給人查

不認同 為什麼不是精簡化實現而是把有複雜度的東西藏起來 這團code怎麼亂七八糟都沒差反正有註解？ 現在一堆東西坑很多就是這樣來的 包含框架甚至語言底層本身如果你不去仔細研究也會被坑到寫程式有兩種方式 一種是把程式寫的很簡單 明顯不容易有缺陷 一種是寫的很複雜 讓別人看不出有明顯的缺陷依照這樣搞你邊寫沒寫可以模糊焦點的註解 還可以邊藏bug和洞

有沒有可能一段程式複雜到需要註解的時候就是應該再拆分它然後把功能單一化的時候?

我的經驗是，通常不是程式複雜到需要註解，而是因應特殊需求而出現的程式需要，他可能寫死很多地方，程式風格明顯不符，或根本是糞code，但暫時需要

我們非英語系國家 不然解法就是在method名稱上取一個好一點的名稱讓大家所見即所得 然後一個method盡量只做一件事但一堆人英文不好ABC狗嘎D method名稱亂取一通

好文，推註解是要說明為什麼，而不是幹什麼

有一種狀況就是我不知道為什麼，所以我寫了它幹什麼...

// ［MOLYXXXXXX]

複雜和不複雜還是不複雜好多了 複雜本身也會掩蓋程式真實的目的 學著用本身是種痛苦不說 學到的東西也是皮毛 也沒什麼高深的哲學用來提升自己 就是硬塑造的技術壁壘不複雜就容易追蹤程式碼 再差也差不過一堆你不爬文就不知道怎麼回事的東西

寫code一樣註解新手滿容易犯，Review別人code有助進步

推

感謝分享～

推

註解不寫…，那其實等於沒寫過什麼重要的東西。所以才養成不寫註解

當你覺得這段 code 未來會有人來問你為什麼這樣寫時，就代表該留點註解了

推

推樓樓上

重要的東西照樣不寫 要寫其實文檔好過註解就現況來看清晰好了解的註解根本沒有 因為人人都不愛寫 都是叫別人寫頤指氣使自己要寫堆三阻四 給人製造障礙要看那堆垃圾註解 不如程式本身簡單質量好看到最後還是自己分析程式比較快

註解優於文件的點在於修改出出程式時可以一併集中修改，不需要大老遠去找文件出來改。另一方面，在不願寫註解的情境下，更不可能願意去翻找並維護離程式碼更遙遠的文件。除非在包含系統整體設計與脈絡時，另外管理的文件才會展現出優勢

註解是分散的 你改一個以為相關的不用改？文檔具有統一性更好些 大專案重要的是整體架構註解表達的是片面的 只是講述區塊的程式你也不可能逐字講解 本身表達力就不足至於找文件...一個quick open快捷鍵就打開了好嗎 還可以內文檢索如果會vi/vim那就更強了

我想兩個都有是比較理想的情況，雖然實際情況很常兩個都沒有

沒什麼好說的 從來沒有刪掉註解的除非註解寫錯了