沒有什麼可以比一段放對位置的註解,更能提供助益。沒有什麼可以比一段無聊教條式的註解,更能弄亂模組。也沒有什麼可以比一段陳舊而混沌不清的註解,更能傳播傷害性的謊言及提供錯誤的資訊。
曾經我以為註解多多益善,然而在閱讀完這些書籍及課程後顛覆了我原有的認知。
當程式碼與註解不符時,你相信什麼?
The ultimate comment for the code is the code itself.
- Hamedani
適當地使用註解是用來「彌補我們用程式碼表達意圖的失敗」
- Uncle Bob.
這幾句話足以充分表達這篇文章接下來想描述的。註解並無法彌補糟糕的程式碼,請修改程式碼表達你的本意。
看了上述說明,好像寫了註解就 Low 了,就等同於承認自己程式沒寫好一般。所以這裡有一個思考邏輯的陷阱特別注意:
寫註解 → 程式碼寫得不好 ≠ 不寫註解 → 程式碼寫得好
雖然說在 Clean Code 的思維中並不鼓勵撰寫註解,但那是在程式碼提供充分可讀性的前提下,若沒辦法寫出漂亮的程式碼,那就還是乖乖寫註解吧。
必要且有益的註解:
- 法律型的註解
- 資訊型的註解
- 對意圖的解釋
- 闡明
- 對後果的告誡
- TODO
- 放大重要性
- 公用 API 的 document
常見的糟糕註解:
- 碎念
- 多餘的註解(廢話)
- 誤導型的註解
- 規定型的註解
- 日誌型的註解
好好的使用版控工具吧!不要再使用這種上古時期的作法了~
- 干擾型的註解
- 位置標幟物
- 右大括弧後面的註解
請善用 IDE 克服這樣的需求,若無法克服,該換 IDE 了...。
- 註解起來的程式碼
這是相當常見的情況,也相當可怕。一旦這部份程式碼移轉給他人維護,就再也沒有人敢刪除,將成為歷史遺跡長存在檔案中。現在都應該有版控,可以追回這些程式碼。大膽刪除吧!但其實我自己也有遇到兩難無法刪除的情況... :p
總結
- 不要寫註解,請重寫你的程式碼!
- 不需要解釋「是什麼」,它應該要是顯而易見的。
- 若真要註解,請解釋「為什麼」與「如何做」。
※ 文中白底截圖均為「無瑕的程式碼」書中圖片。