[Clean Code] 註解 Comment

沒有什麼可以比一段放對位置的註解,更能提供助益。沒有什麼可以比一段無聊教條式的註解,更能弄亂模組。也沒有什麼可以比一段陳舊而混沌不清的註解,更能傳播傷害性的謊言及提供錯誤的資訊。

曾經我以為註解多多益善,然而在閱讀完這些書籍及課程後顛覆了我原有的認知。

 

當程式碼與註解不符時,你相信什麼?

The ultimate comment for the code is the code itself.
                                                                                      - Hamedani

適當地使用註解是用來「彌補我們用程式碼表達意圖的失敗
                                                                                      - Uncle Bob.

這幾句話足以充分表達這篇文章接下來想描述的。註解並無法彌補糟糕的程式碼,請修改程式碼表達你的本意。
 

看了上述說明,好像寫了註解就 Low 了,就等同於承認自己程式沒寫好一般。所以這裡有一個思考邏輯的陷阱特別注意:

寫註解 → 程式碼寫得不好  ≠   不寫註解 → 程式碼寫得好

雖然說在 Clean Code 的思維中並不鼓勵撰寫註解,但那是在程式碼提供充分可讀性的前提下,若沒辦法寫出漂亮的程式碼,那就還是乖乖寫註解吧。

 

必要且有益的註解:

  • 法律型的註解
  • 資訊型的註解
  • 對意圖的解釋
  • 闡明
  • 對後果的告誡
  • TODO
  • 放大重要性
  • 公用 API 的 document

 

常見的糟糕註解:

  • 碎念
  • 多餘的註解(廢話)
  • 誤導型的註解
  • 規定型的註解
  • 日誌型的註解
    好好的使用版控工具吧!不要再使用這種上古時期的作法了~
  • 干擾型的註解
  • 位置標幟物
  • 右大括弧後面的註解
    請善用 IDE 克服這樣的需求,若無法克服,該換 IDE 了...。
  • 註解起來的程式碼
    這是相當常見的情況,也相當可怕。一旦這部份程式碼移轉給他人維護,就再也沒有人敢刪除,將成為歷史遺跡長存在檔案中。現在都應該有版控,可以追回這些程式碼。大膽刪除吧!但其實我自己也有遇到兩難無法刪除的情況... :p

 

總結

  • 不要寫註解,請重寫你的程式碼!
  • 不需要解釋「是什麼」,它應該要是顯而易見的。
  • 若真要註解,請解釋「為什麼」與「如何做」。

 

※ 文中白底截圖均為「無瑕的程式碼」書中圖片。