Re: [請益] 寫註解到底是不是好習慣

[AmosYang (泛用人型編碼器)]

先說結論：「二分法命題比較有得戰、比較熱鬧；若像下面這樣去考量各種層面的
話，會很無聊 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://www.ptt.cc/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://www.ptt.cc/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://www.ptt.cc/bbs/Soft_Job/M.1546163575.A.4C5.html
推 oneheat: 你這個太無聊了，應該沒幾個人會回
XD

※ 編輯: AmosYang (136.56.102.149), 12/30/2018 17:57:44
※ 編輯: AmosYang (136.56.102.149), 12/30/2018 17:59:12
推 t64141: 光第一句就該推了XD
此串開頭原po在解 天才小釣手 的成就 XD
※ 編輯: AmosYang (136.56.102.149), 12/30/2018 18:05:13
推 t64141: 看完，再推一次
→ pttworld: 註解分類是有意義的，討論串某些推文明顯和內文不同類
→ yougigun: end
推 landlord: 言之有物，推！
推 jaspreme206: 推
推 nelley: 推這篇
推 v86861062: :)
[編輯補充]  就「人體工程」這個題目，可以參考 qrtt1  寫的這篇:
https://www.ptt.cc/bbs/Soft_Job/M.1546144956.A.439.html
※ 編輯: AmosYang (136.56.102.149), 12/30/2018 19:18:37
→ qrtt1: 用人體有色色的感覺
推 babelism: 九類註解很值得借鑑,和我的觀點重合處甚多
推 sa074463: 推
推 rollr: 水準太高
推 Ghamu: 事實上就有好的有不好 應該的 不應該的註解這樣
→ Ghamu: 但一堆真的都拿爛註解來說該寫註解好棒棒 真的不敢恭維
推 kyrie77: 推這篇
推 freepenguin: 推
推 Ouranos: 推推~
推 pttuser2266: 原本很好戰的主題，不要打擾我我看戲
推 ppc: 推個
推 vn509942: 感謝大大整理分享
推 agra: 這個切分分類視角很不錯，有看有推！
推 polola6212: 這串下來只有這篇有營養........
推 crow1270: 推
推 leicheong: Warning comments: 當你在用第三方程式庫有gotcha
→ leicheong: 例如statement需要特定順序執行或者有bug而需要
→ leicheong: workaround, 而說明文件沒標示 (例如微軟去年公佈必須
→ leicheong: 開啟SMB1才能正常運作的軟體清單... 很多人一直都沒
→ leicheong: 想到SMB1居然會被更新停用, 而且沒幾個人會知道在用
→ leicheong: 的lib的技術細節吧)這些一定得下註解
→ rocwild: 簡單說就是看寫什麼樣的註解吧。比如說“問題(problem)
→ rocwild: ”也是一種註解。