《A Philosophy of Software Design》心得 3 — 寫程式時該寫註解 (comments) 嗎?如果要的話該怎麼寫?

2023年1月15日

💎 加入 E+ 成長計畫 與超過 250+ 位軟體工程師一起在社群中成長,並且獲得更深入、系統性軟體工程內容

每當提到在程式中寫註解 (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

要怎麼判斷你寫的這段註解是不是跟程式碼本身一樣? 書中提到,在你寫完註解後可以問問自己「如果某個之前沒讀過這段程式碼的人,能不能看著這段註解寫出程式碼?」如果可以的話,就代表註解只是在描述程式碼,而不是在解釋為什麼這樣寫該段程式碼。因此,在寫完註解後,可以再比對一下程式碼與註解,如果你的註解像是下面那長梗圖一樣 (程式碼本身是 Stop Sign,然後註解寫著「這是一個 Stop Sign」),這種狀況下註解就真的沒有額外價值,不推薦寫。

重複程式碼的註解就像這個立牌一樣 This is a stop sign -> Stop Sign
重複程式碼的註解就像這個立牌一樣 This is a stop sign -> Stop Sign
圖片來源:《A Philosophy of Software Design》

從讀者的角度出發

最後 John Ousterhout 教授提到,寫註解要從程式碼讀者的角度出發,要思考有哪些關鍵資訊是讀者不知道的。特別是在程式碼審查 (code review) 時,如果你寫的某段程式碼讓別人說很難懂,或者某個資訊讓別人說並不顯而易見,這時候不要去跟對方爭,而是去想為什麼對方會有困惑,以及你可以如何靠註解讓程式碼更好被理解。

(文末備註:這個章節本身有很多範例,但為了避免筆記變太長,就僅有放其中一個。有興趣透過案例更具體了解作者的觀點的話,推薦直接買這本書來讀)。


《A Philosophy of Software Design》心得系列文

🧵 如果你想收到最即時的內容更新,可以在 FacebookInstagram 上追蹤我們