作者AmosYang (泛用人型編碼器)
看板Soft_Job
標題Re: [請益] 寫註解到底是不是好習慣
時間Sun Dec 30 17:52:48 2018
先說結論：「二分法命題比較有得戰、比較熱鬧；若像下面這樣去考量各種層面的
話，會很無聊 XD 。」
# 從 電腦科學 的角度來看
所謂「寫程式」的「寫」，在抽象意義上即是「表達(express)」 ；每種實用的語
言多半有其強項與短處，也就是方便與不方便的用途。
例如說，用 程式語言 來表達計算(computation)過程 ，尤其是表達給電腦看的計
算指令，通常來說會比用 自然語言 來得方便。
用 自然語言 (配合科學/數學符號) 來描述、解釋問題，尤其是表達給人腦看的脈
絡上下文(context) ，通常來說會比用 程式語言 來得方便。
是故，如果一個問題(problem) 是簡單(simple)到可以從其
計算解決方案(solution)去反推出問題的全貌，那麼，的確用程式語言去描述計算
過程就可以了，也就是「不太需要去寫註解」。
反之，如果一個問題的複雜度高，或其脈絡是難以用程式語言去描述的，那麼，就
可以用自然語言這個更適合的工具，去描述該問題的脈絡，也就是「有寫註解的價
值」。
有興趣的話，可以參考 DSL/GPL 的觀念:
*
https://en.wikipedia.org/wiki/Domain-specific_language
*
https://en.wikipedia.org/wiki/General-purpose_language
# 從 軟體工程 的角度來看
前面板友 ThxThx 在推文 [1] 裡點出的文章，有更深入完整地探討這個方向。
*
http://antirez.com/news/124
*
https://www.reddit.com/9m6ahs
Hacker News 上也討論過 antirez 的那篇文。
*
https://news.ycombinator.com/item?id=18157047
[1]:
https://webptt.com/m.aspx?n=bbs/Soft_Job/M.1546056944.A.99E.html
以下是對原文的摘要，加上簡略的、我的解讀與看法；作者 antirez 把註解分為
9 大類如下，且主張：「前 6 大類是相對有正面價值的，後 3 大類則有疑慮
。」
> * Function comments
「函式註解」，可以想成「介面(interface), API 」註解。
> * Design comments
設計藍圖、大方向的註解。
> * Why comments
相對於描述「如何(how)」的程式碼 ，解釋「意圖、原因」的註解。
> * Teacher comments
深入解釋「問題的脈絡/領域(domain)」的註解 ，例如，某數學公式的由來
。
> * Checklist comments
列出「提醒/警示」的清單註解 ，例如，幫助後人避免踩中技術細節的地雷。
> * Guide comments
「導讀」註解。
> * Trivial comments
解釋「不言自明」之事的註解；讀這類註解所需要花的精神，不見得比直接讀程式碼
來得少，且不見得能幫助讀者更了解此程式要解決的問題。
> * Debt comments
技術債註解；或許應該以 issue/bug 的方式記錄技術債，而不是藏在程式碼
裡。
> * Backup comments
以 備份 為目的，把舊的程式碼以註解的方式留在程式碼檔案裡。
易言之，不同型式的註解有不同的用途與價值。
# 從 人體工程 的角度來看
相對於 軟體工程 ， 人體工程 XD 是更困難的。
真正的問題通常不是技術問題，而是認知、環境、歷史等脈絡上的問題，尤其是那
些「沒有被說出來 / 沒有便利的共同語言去表達」 的東西。
那些東西對輕重緩急的取捨拿捏有極顯著的影響與衝擊，卻又常常是無影無形難以
捕捉、表達、溝通。
(「人體工程」離原主題太遠了，就此打住。)
[編輯補充] 就「人體工程」這個題目，可以參考 qrtt1 寫的這篇:
https://webptt.com/m.aspx?n=bbs/Soft_Job/M.1546144956.A.439.html
# 結論
扁平化、二分法命題比較有得戰、比較熱鬧；若像上面這樣去考量各種層面、脈絡
的話，會很無聊，很難戰 XD 。
--
個人 雜談、學習、英語、軟體
https://www.facebook.com/tw.yang.30 https://www.facebook.com/30abysses/
https://twitter.com/twy30 http://www.30abysses.com/
--
※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 136.56.102.149
※ 文章網址: https://webptt.com/m.aspx?n=bbs/Soft_Job/M.1546163575.A.4C5.html
1F：推 oneheat: 你這個太無聊了，應該沒幾個人會回 12/30 17:54
XD
※ 編輯: AmosYang (136.56.102.149), 12/30/2018 17:57:44
※ 編輯: AmosYang (136.56.102.149), 12/30/2018 17:59:12
2F：推 t64141: 光第一句就該推了XD 12/30 17:58
此串開頭原po在解 天才小釣手 的成就 XD
※ 編輯: AmosYang (136.56.102.149), 12/30/2018 18:05:13
3F：推 t64141: 看完，再推一次 12/30 18:02
4F：→ pttworld: 註解分類是有意義的，討論串某些推文明顯和內文不同類 12/30 18:07
5F：→ yougigun: end 12/30 18:16
6F：推 landlord: 言之有物，推！ 12/30 18:17
7F：推 jaspreme206: 推 12/30 18:18
8F：推 nelley: 推這篇 12/30 18:51
9F：推 v86861062: :) 12/30 19:02
[編輯補充] 就「人體工程」這個題目，可以參考 qrtt1 寫的這篇:
https://webptt.com/m.aspx?n=bbs/Soft_Job/M.1546144956.A.439.html
※ 編輯: AmosYang (136.56.102.149), 12/30/2018 19:18:37
10F：→ qrtt1: 用人體有色色的感覺 12/30 19:47
11F：推 babelism: 九類註解很值得借鑑,和我的觀點重合處甚多 12/30 22:35
12F：推 sa074463: 推 12/30 23:00
13F：推 rollr: 水準太高 12/31 01:39
14F：推 Ghamu: 事實上就有好的有不好 應該的 不應該的註解這樣 12/31 02:11
15F：→ Ghamu: 但一堆真的都拿爛註解來說該寫註解好棒棒 真的不敢恭維 12/31 02:13
16F：推 kyrie77: 推這篇 12/31 02:53
17F：推 freepenguin: 推 12/31 11:33
18F：推 Ouranos: 推推~ 12/31 13:40
19F：推 pttuser2266: 原本很好戰的主題，不要打擾我我看戲 12/31 14:13
20F：推 ppc: 推個 12/31 14:40
21F：推 vn509942: 感謝大大整理分享 01/01 10:49
22F：推 agra: 這個切分分類視角很不錯，有看有推！ 01/01 14:13
23F：推 polola6212: 這串下來只有這篇有營養........ 01/03 01:39
24F：推 crow1270: 推 01/03 19:09
25F：推 leicheong: Warning comments: 當你在用第三方程式庫有gotcha 01/04 21:11
26F：→ leicheong: 例如statement需要特定順序執行或者有bug而需要 01/04 21:11
27F：→ leicheong: workaround, 而說明文件沒標示 (例如微軟去年公佈必須 01/04 21:13
28F：→ leicheong: 開啟SMB1才能正常運作的軟體清單... 很多人一直都沒 01/04 21:14
29F：→ leicheong: 想到SMB1居然會被更新停用, 而且沒幾個人會知道在用 01/04 21:15
30F：→ leicheong: 的lib的技術細節吧)這些一定得下註解 01/04 21:16
31F：→ rocwild: 簡單說就是看寫什麼樣的註解吧。比如說“問題(problem) 01/05 11:41
32F：→ rocwild: ”也是一種註解。 01/05 11:41