本來以為程式碼註解這種事情應該是業界的共識，但是最近看到一些網路上的討論才發現，存在一派的人（例如這個影片）反而是明確地反對使用註解，他們的立論主要有幾點：
- 程式碼的本身的意義可以藉由好的命名規範、函式抽離重構、型別宣告與模組化等方法來自我呈現出來；這些有做好的話，程式碼本身一看就知道是在幹嘛，並不需要另外使用文字加以解釋。
- 實務上，很多時候程式碼在修改了之後、註解並沒有也跟著更新，這使得維護的人反而需要花額外的成本去確定註解跟程式碼的一致性、否則就反而會被過時的註解誤導。
- 程式碼是可以有效地透過編譯器和 linting 工具來自動檢查的，但是註解卻暫時並沒有有效的手段可以自動檢查其正確性（也許 AI 發達的未來可以，但是現在還很不方便）。
因此，他們覺得應該把重點放在撰寫出本身好閱讀的程式碼，然後根本不要使用註解。
不過我並不認同這樣的一種觀點。最主要地，好閱讀的程式碼或許可以呈現出程式碼的「what」（寫了什麼），但是卻仍然沒有辦法呈現出程式碼的「why」（為什麼要這樣寫），而後者在我看來才是註解的真正精髓所在。很多時候，程式寫了之後過了一段時間，我回去看過去寫的程式碼時常常會質疑「當初為什麼我要這樣寫？這必要嗎？是否可以刪掉這一段、或加以簡化？」，而如果當初我沒有把撰寫的理由註解下來的話，我就很容易浪費許多時間把當初的思考歷程重走一遍。所以現在只要是遇到一段程式碼是我覺得背後的理由並不顯然的，我不但會加以註解，還常常會在註解當中附上對應的參考資料連結等等以方便未來查閱。後者也是很重要的：因為程式碼背後的理由也是有可能會隨著框架套件等等的改版而過時的，附上那些參考資料有助於讓我未來需要重新評估某些程式碼的時候、可以快速地掌握之前的脈絡。這些都不是靠程式碼本身就能做到的。
再來，光靠程式碼本身是否就能有效傳達出程式碼的「what」，這點我也是大大存疑的。不管多麼好閱讀的程式碼，也還是不可能比得上自然語言要來得好閱讀；閱讀程式碼是需要大腦額外地進行理解和整理的功夫，但自然語言卻可以直接把那些整理過後的重點直接呈現出來，不但節省理解上的負擔、也可以免於閱讀一些次要的流水帳。此外 doc 類型的註解還可以在滑鼠移到識別項上面的時候直接顯示出來，使得我們不用切換檔案檢視就可以直接看到一些最重要的資訊，這即便是落實到極致的命名規範也不可能同樣程度地有效。
最後，「程式碼更新、但註解沒有跟著更新」這種事情透過 Git 是非常容易抓出來的，所以如果有這方面的問題，我會有點質疑這個團隊是否有好好落實 code review。如果連這麼容易抓出的問題都沒有在 code review 中被發現，跟我說他們的團隊就反而有辦法寫出好閱讀的高品質程式碼，這怎麼聽都很匪夷所思。即使有自動 linting，也只能診斷出最基本的可讀性問題，這跟「程式碼可以自明地呈現其邏輯」完全是兩個不同層次的事。我無法想像為什麼困難的後者做得到、簡單的更新註解反而就做不到。
真的要說的話，我覺得他們的觀點只有在一種情況下能成立，就是他們的程式碼實在是沒學問到了「就算註解也只是照本宣科」的那種地步、完全沒有更深入的洞見可以補充了。這種專案當然不是沒有，而且還多得很，但是如果一個軟體工程師做過的通通都是那種專案、乃至於他會形成這種反對註解的觀點，那他真的應該再多看看更廣大的世界才是。
留言