Re: [心得] 好的註解是解釋為何需要這段 code

※ 引述《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 教授的觀點一樣， 就是註解要解釋背後的「為什麼」，而不是把程式碼做的事重複說一次。 ------ (以下是我讀完該章節後整理的筆記) ------ ## 網誌好讀版： http://bit.ly/3WdTo1b 每當提到在程式中寫註解 (comments)，你大概會在網路上看到兩派人馬，有人覺得應該 要寫註解；又有另一群人覺得程式碼應該要寫得夠清楚，如果有註解就代表寫不夠清楚， 應該要重構而不是加註解。當然除了這極端的兩派人馬外，多數人都是在中間，部分的程 式碼寫註解，但不會全部都寫。 關於寫註解這件事，在 《A Philosophy of Software Design》 書當中也有談及。John Ousterhout 教授的觀點是，如果註解寫得好，將有效改善整體的系統設計。假如你是反 註解派的人，或許可以一起來讀讀他為什麼這麼認為。 ## 程式本身寫得夠清楚，就不用註解嗎? 「程式本寫得夠清楚，就不用註解」是很多人認為不該寫註解的第一大理由。然而程式本 身或許可以清楚表達該程式碼做的事，但不能解釋「為什麼」要這樣寫，也不能解釋在什 麼情境可能比較適合某個方法。對於這些相對後設 (meta) 的內容，註解就是很好的幫手 。 更進一步說，好的軟體設計，應該要把複雜度藏起來，要藏起複雜度，我們需要抽象化， 讓其他使用該段程式碼的開發者，可以不用去管背後的細節。因此，如果一個開發者，還 要去讀程式的細節才能懂如何用該函式或方法，那就失去抽象化的意義。寫註解可以讓其 他開發者，不用去讀程式裡頭的細節也知道如何用該函式或方法，這才能達到抽象化的意 義。因此不論程式本身寫的清楚與否，好的抽象化搭配好的註解，都是對整個程式庫的維 護有幫助的。 ## 別說你沒時間寫註解 在開發時，很多開發者會認為寫註解的優先順序比較低，因此會想把時間花在寫新功能， 而不是為已經開發好的功能寫註解。然而在軟體開發中，永遠有寫不完的功能，如過說因 為要開發新功能而沒時間寫註解，就永遠不會有註解。從長遠的角度來看，這樣的代價是 程式庫的可維護性會降低。如果從效益與成本的角度來看，寫註解的時間，會遠比其他開 發者花在弄懂沒註解的程式所花的時間要少很多。 ## 不要找其他不寫註解的理由 很多開發者也會找其他理由不寫註解。例如認為註解如果沒隨著程式更新，反而會誤導人 ；或者是因為過去讀過別人寫的註解覺得沒用，就認為註解沒有用。這些都是外部因素， 無法證成註解本身沒有效益。此外這些都是可以透過好的流程而解決的，所以作者認為不 要找這些理由不寫註解，而是要去打造更好的流程來改善這些問題。 ## 寫註解的好處 上面談了這麼多，大概可以看出 John Ousterhout 教授有強烈的觀點認為要寫註解。不 過回過頭來說，寫註解有什麼好處呢? 他認為最大的好處在於註解可以捕捉到程式碼沒辦 法傳達的資訊，這能夠讓未來要維護這段程式碼的開發者，能夠更快速地上手。特別對於 團隊中加入的新成員，程式碼中的註解可以大幅降低讀程式的認知負擔 (cognitive load)，以及減少未知。 如果沒有記錄下這些脈絡與原因，未來的開發者就不會知道為什麼當初是這樣寫，這變得 只能猜測原作者的意圖。這不僅更耗時，也可能會因為理解錯原本的意圖，導致在維護該 段程式碼時出錯。很多時候，未來要維護程式碼的是自己，許多人在寫完某段程式碼幾個 月後，可能忘了自己當初為什麼這樣寫，所以寫註解不僅是幫助其他開發者，也很可能是 在幫助未來的自己。 ## 註解該寫什麼? 雖說 John Ousterhout 教授的觀點是認為寫註解對軟體設計有幫助，但他也同意不是什 麼都該寫成註解。他認為只有在程式碼中不顯而易見的才該寫註解 (comments should describe things that aren’t obvious from the code)。 在軟體設計中最重要的抽象化，即是提供一個更簡易的思考方式，讓開發者可以不用深入 過於細節的部分。即使開發者可以透過細讀程式碼來了解其如何運作，但這樣做太花時間 。John Ousterhout 教授的觀點認為開發者應該要不讀程式碼內容，即可理解模組提供的 抽象化，而註解是能夠協助做到這樣的方法。 ## 不要重複程式碼本身 前面提到，註解應該要講「為什麼」這樣寫，而不是講程式碼在做什麼。畢竟程式碼本身 就代表程式碼在做的事，如果註解在寫一次，會是多此一舉。下面是書中提到的負面教材 ，基本上註解就是把程式碼做的事情。 ptr_copy = get_copy(obj) # Get pointer copy if is_unlocked(ptr_copy): # Is obj free? return obj # return current obj if is_copy(ptr_copy): # Already a copy? return obj # return obj thread_id = get_thread_id(ptr_copy) if thread_id == ctx.thread_id: # Locked by current ctx return ptr_copy # Return copy 要怎麼判斷你寫的這段註解是不是跟程式碼本身一樣? 書中提到，在你寫完註解後可以問 問自己「如果某個之前沒讀過這段程式碼的人，能不能看著這段註解寫出程式碼?」如果 可以的話，就代表註解只是在描述程式碼，而不是在解釋為什麼這樣寫該段程式碼。因此 ，在寫完註解後，可以再比對一下程式碼與註解，如果重複就真的不推薦寫。 ## 從讀者的角度出發 最後 John Ousterhout 教授提到，寫註解要從程式碼讀者的角度出發，要思考有哪些關 鍵資訊是讀者不知道的。特別是在程式碼審查 (code review) 時，如果你寫的某段程式 碼讓別人說很難懂，或者某個資訊讓別人說並不顯而易見，這時候不要去跟對方爭，而是 去想為什麼對方會有困惑，以及你可以如何靠註解讓程式碼更好被理解。 (文末備註：這個章節本身有很多範例，但為了避免筆記變太長，就僅有放其中一個。有 興趣透過案例更具體了解作者的觀點的話，推薦直接買這本書來讀)。 -- 南漂一不小心漂到了新加坡 https://www.explainthis.io/zh-hant/singapore -- ※ 發信站: 批踢踢實業坊(ptt.cc), 來自: 116.86.64.199 (新加坡) ※ 文章網址: https://www.ptt.cc/bbs/Soft_Job/M.1673785027.A.36D.html