註解 （Comments） #

核心觀點 #

在軟體開發中，註解（Comments）是把雙面刃。作者指出，註解的存在往往是為彌補程式碼未能充分表達意圖的失敗。 最好的說明文件就是程式碼本身。如果你的程式碼夠整潔、命名夠精準，你根本不需要註解。

• 別給糟糕的程式碼寫註解，重寫它！
• 整潔具表達力但極少註解的程式碼，遠勝錯亂複雜又充滿註解的程式碼
• 註解無法隨程式碼同步更新，陳舊註解會散播謊言並提供錯誤資訊

什麼是「合理註解」？ #

雖然目標是減少註解，但某些特定情境下，註解是必要且有益的：

1. 法律資訊 (Legal Comments)： 如版權聲明或授權條款，這是必須存在的。

   // Copyright (C) 2023 by ...
   

2. 傳達資訊 (Informative Comments)： 提供對正則表達式或特殊格式的說明，幫助讀者快速理解。

   // format matched kk:mm:ss EEE, MMM dd, yyyy
   Pattern timePattern = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");
   

3. 解釋意圖 (Explanation of Intent)： 不僅解釋「做了什麼」，更重要的是解釋「為什麼這樣做」。 例如，為避開某個已知 Bug 或競爭條件（Race Condition）。

   // This is our best attempt to get a race condition
   // by creating a large number of threads.
   

4. 告誡後果 (Warning of Consequences)： 警告其他開發者某些操作的風險，例如執行時間過長或線程不安全。

   // SimpleDateFormat is not thread safe,
   // so we need to create each instance independently.
   

5. 代辦事項 (TODO Comments)： 記錄目前無法完成但未來要處理的工作（但在現代開發中，應定期清理這些 TODO）。

   // TODO: Handle the condition where the user is not logged in
   

6. 放大重要性 (Amplification)： 強調某個看似不重要但實際有關鍵影響的細節。

   String trimmed = input.trim(); // The trim is really important.
   

什麼是「糟糕的註解」？ #

多數註解都屬於此類。它們通常是藉口、懶惰或對程式碼掌控力不足的表現。

1. 雜訊與多餘 (Redundant & Noise) #

• 自言自語： 寫給自己看的筆記，別人看不懂
• 多餘的註解： 讀程式碼就知道的事，不需要再寫成文字

  i++; // increment i
  

• 僅為格式存在： 規定每個函式都要有 Javadoc，只會導致充滿廢話的註解。

2. 誤導與過時 (Misleading) #

• 隨著程式碼修改，註解往往被遺忘而沒有更新。
• 一段位置正確的註解能提供效益；但一段陳舊註解會變成謊言。

3. 版本控制的職責 (Version Control Tasks) #

有些資訊應交給 Git 等版本控制系統，而不是寫在程式碼裡：

• 日誌型註解 (Journal Comments)： 不需像寫日記一樣在檔案開頭記錄每次修改的日期與內容
• 簽名 (Attribution)： 不需標註 // Written by Bob，Git log 已紀錄了一切

4. 被註解掉的程式碼 (Commented-Out Code) #

這是最令人討厭的壞習慣。

嚴禁保留被註解的程式碼！
其他人看到這段程式碼會不敢刪除，擔心它是否隱含什麼重要功能，導致程式碼越來越髒亂。請相信你的版本控制系統，直接刪除它。

5. 範圍錯誤 #

• 全域資訊： 不要在一個小函式的註解中討論系統性的全域資訊
• 非本地資訊： 註解應只描述附近程式碼，不要描述遠處的模組

結論 #

好的命名與重構通常能取代註解需求。 當想寫註解時，先停下來思考：「我能不能透過修改變數名稱或重構邏輯，讓程式碼自己說話？」

“Truth can only be found in one place: the code.”
真相只有一個地方找得到：程式碼。