這章節的重點就在目錄：

註解原則：

  • 【註解無法彌補糟糕的代碼】
  • 【用好的程序表達你的本意】

好的註解：

  • README：

每個文件開頭的標準註解

// Copyright (c) 2019 by ~
// Released ~ Lincense version 2
  • 資訊型註解：對一些方法的額外註解（例如終止遞歸的條件是啥，或是這段代碼在做啥），當然如果用代碼就能解釋那是最棒的。
  • 意圖的解釋：為啥會有這種寫法？當時有什麼考量？是為了確保什麼業務嗎？
  • 重要的告誡：例如此段代碼是線程不安全，或是這段代碼不能改動不然會爆炸
  • 右大括號後的註解：這個要看情況，嵌套函數過多的註解是有意義的
  • TODO：待辦事項，解決完就移除吧


不好的註解（我曾經有過的行為，或在項目裡看過的註解）：

  • 多餘的註解：沒有比代碼透露更多資訊的註解
  • 干擾的註解：誤導人！
  • 日誌型註解：把註解當作版控
  • 出處及署名：跟把註解當作版控一樣行為
  • 被註解起來的代碼：每次看到這個都很火大，也不知道能不能刪除，看了都礙眼