Skip to content

Latest commit

 

History

History
169 lines (117 loc) · 6.62 KB

2018-12-30-commenting.md

File metadata and controls

169 lines (117 loc) · 6.62 KB
作者 AmosYang (泛用人型編碼器)
看板 Soft_Job
標題 Re: [請益] 寫註解到底是不是好習慣
時間 Sun Dec 30 17:52:48 2018

先說結論：「二分法命題比較有得戰、比較熱鬧；若像下面這樣去考量各種層面的 話，會很無聊 XD 。」

從 電腦科學 的角度來看

所謂「寫程式」的「寫」，在抽象意義上即是「表達(express)」 ；每種實用的語 言多半有其強項與短處，也就是方便與不方便的用途。

例如說，用 程式語言 來表達計算(computation)過程 ，尤其是表達給電腦看的計 算指令，通常來說會比用 自然語言 來得方便。

用 自然語言 (配合科學/數學符號) 來描述、解釋問題，尤其是表達給人腦看的脈 絡上下文(context) ，通常來說會比用 程式語言 來得方便。

是故，如果一個問題(problem) 是簡單(simple)到可以從其 計算解決方案(solution)去反推出問題的全貌，那麼，的確用程式語言去描述計算 過程就可以了，也就是「不太需要去寫註解」。

反之，如果一個問題的複雜度高，或其脈絡是難以用程式語言去描述的，那麼，就 可以用自然語言這個更適合的工具，去描述該問題的脈絡，也就是「有寫註解的價 值」。

有興趣的話，可以參考 DSL/GPL 的觀念:

從 軟體工程 的角度來看

前面板友 ThxThx 在推文 1 裡點出的文章，有更深入完整地探討這個方向。

Hacker News 上也討論過 antirez 的那篇文。

以下是對原文的摘要，加上簡略的、我的解讀與看法；作者 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

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 12/30 17:58

此串開頭原po在解 天才小釣手 的成就 XD
※ 編輯: AmosYang (136.56.102.149), 12/30/2018 18:05:13
推 t64141: 看完，再推一次 12/30 18:02
→ pttworld: 註解分類是有意義的，討論串某些推文明顯和內文不同類 12/30 18:07
→ yougigun: end 12/30 18:16
推 landlord: 言之有物，推！ 12/30 18:17
推 jaspreme206: 推 12/30 18:18
推 nelley: 推這篇 12/30 18:51
推 v86861062: :) 12/30 19:02

[編輯補充]  就「人體工程」這個題目，可以參考 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: 用人體有色色的感覺 12/30 19:47
推 babelism: 九類註解很值得借鑑,和我的觀點重合處甚多 12/30 22:35
推 sa074463: 推 12/30 23:00
推 rollr: 水準太高 12/31 01:39
推 Ghamu: 事實上就有好的有不好 應該的 不應該的註解這樣 12/31 02:11
→ Ghamu: 但一堆真的都拿爛註解來說該寫註解好棒棒 真的不敢恭維 12/31 02:13
推 kyrie77: 推這篇 12/31 02:53
推 freepenguin: 推 12/31 11:33
推 Ouranos: 推推~ 12/31 13:40
推 pttuser2266: 原本很好戰的主題，不要打擾我我看戲 12/31 14:13
推 ppc: 推個 12/31 14:40
推 vn509942: 感謝大大整理分享 01/01 10:49
推 agra: 這個切分分類視角很不錯，有看有推！ 01/01 14:13
推 polola6212: 這串下來只有這篇有營養........ 01/03 01:39
推 crow1270: 推 01/03 19:09
推 leicheong: Warning comments: 當你在用第三方程式庫有gotcha 01/04 21:11
→ leicheong: 例如statement需要特定順序執行或者有bug而需要 01/04 21:11
→ leicheong: workaround, 而說明文件沒標示 (例如微軟去年公佈必須 01/04 21:13
→ leicheong: 開啟SMB1才能正常運作的軟體清單... 很多人一直都沒 01/04 21:14
→ leicheong: 想到SMB1居然會被更新停用, 而且沒幾個人會知道在用 01/04 21:15
→ leicheong: 的lib的技術細節吧)這些一定得下註解 01/04 21:16
→ rocwild: 簡單說就是看寫什麼樣的註解吧。比如說“問題(problem) 01/05 11:41
→ rocwild: ”也是一種註解。 01/05 11:41