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

看板Soft_Job (軟體人)作者AmosYang (泛用人型編碼器)時間7年前 (2018/12/30 17:52)推噓21(21推 0噓 11→)

留言32則, 24人參與討論串22/24 (看更多)

先說結論：「二分法命題比較有得戰、比較熱鬧；若像下面這樣去考量各種層面的話，會很無聊 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

12/30 17:54, 7年前 , 1^F

12/30 17:54, 1^F

XD ※ 編輯: AmosYang (136.56.102.149), 12/30/2018 17:57:44 ※ 編輯: AmosYang (136.56.102.149), 12/30/2018 17:59:12

推

t64141

12/30 17:58, 7年前 , 2^F

12/30 17:58, 2^F

此串開頭原po在解天才小釣手的成就 XD ※ 編輯: AmosYang (136.56.102.149), 12/30/2018 18:05:13

推

t64141