[學習筆記] 《程式碼整潔之道》—第4章 註釋

• 什麼也比不上放置良好的註釋來的有用！

• 什麼麼也比不上亂七八糟的註釋更有本事搗亂一個模組！

• 什麼也不會比陳舊、提供錯誤資訊的註釋更有破壞性！

• 註釋的恰當用法是彌補我們程式碼表達意圖時的失敗。

  • 註釋總是一種失敗；
  • 註釋會撒謊：主食存在的時間越久，就離所描述的程式碼越遠，越來越變得全然錯誤。

• 程式設計師應當負責將註釋保持在可維護、有關聯、和精確的高度。

  • 不準確的註釋要比沒有註釋還糟糕。

• 唯一真實的就是程式碼！

  • 儘管有時需要註釋，我們也該多花心思儘量減少註釋。

註釋不能美化糟糕的程式碼

• 寫註釋的常見動機之一就是糟糕的程式碼
  的存在。
  • 帶有少量註釋的整潔而又表達力的程式碼，要比帶有大量註釋的零碎而複雜的程式碼像樣得多。
  • 與其花時間編寫解釋糟糕程式碼的註釋,不如花時間清潔那堆糟糕的程式碼。

用程式碼來闡述

• 有時，程式碼本身不足以解釋其行為

  • 有的程式設計師認為：程式碼很少 —> 如果有的話 —> 能做好解釋工作 （錯誤！！！）

    // Check to see if the employee is eligible for full benefits
    if((employee.flags & HOURLY_FLAG) &&
       (employee.age >65))
     
    
    
    // 或許你更願意看到這個
    if(employee.isEligibalForFullBenefits())
    

• 只要多花一點時間，就能用程式碼解釋你大部分意圖。

好註釋

有些註釋是必須的，也是有利的。

唯一真正好的註釋就是想辦法不去寫的註釋。

• 法律資訊 ：版權及著作權宣告

  // Copyright (C) 2003,2004,2005 by Object Mentor, Inc. All rights reserved.
  // Released under the terms of the GUN General Public License version 2 or later.
  

  • 這類註釋不應該是合同或法典。
  • 只要有可能，就只想一份標準許可或其他外部文件，而不是把所有條款放到註釋中。

• 提供基本資訊

  • 這類註釋有時管用，但更好的方式是儘量用函式名稱傳達資訊。

• 不僅提供了有關實現的有用資訊，還提供了某個決定後面的意圖。

• 把某些晦澀難明的引數或者返回值的意義翻譯為某種可讀形式。

  • 更好的方式是儘量讓引數或返回值滋生足夠清楚。
  • 如果引數或返回值是某個標準庫的一部分，或是你不能修改程式碼，幫助闡述其含義的程式碼就會有用。

• 警告其他程式許願出現某種後果

• 用//TODO 形式在原始碼中放置要做的工作列表。

• 放大某種開來不合理之物的重要性。

• 沒有比被良好描述的公共API更有用和令人滿意的了。

壞註釋

壞註釋都是糟糕的程式碼的支撐和藉口，或者對錯誤決策的修正，基本上等於程式設計師的自說自話。

• 如果只是因為你覺得應該或者過程需要就添加註釋，那就是無謂之舉。

  • 如果你決定寫註釋，就要花必要的時間確保寫出最好的註釋。

• 多餘的註釋

  • 不能比程式碼本身提供更多的資訊
  • 沒有證明程式碼的意義
  • 沒有給出程式碼的意圖或邏輯

• 誤導性註釋

• 循規式註釋

• 日誌式註釋

• 廢話註釋

• 可怕的廢話

  /** The name **/
  private String name;
  
  /** The version **/
  private String version;
  

• 能用函式或者變數時就別用註釋

  // does the module from the global list <mod> depend on the
  // subsystem we are part of?
  if(smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))
  

  改成沒有註釋的版本如下

  ArrayList moduleDependees = smodule.getDependSubsystems();
  String ourSubSystem = subSysMod.getSubSystem();
  if(moduleDependees.contains(ourSubSystem))
  

• 位置標記

• 括號後面的註釋

  try{
      /* ... */
      /* ... */
      while(1){
          /* ... */
          /* ... */
          /* ... */
      } //while
      /* ... */
      /* ... */
  } //try
  catch{
      /* ... */
  } //catch
  

  • 如果你發現自己想標記有括號，其實應該做的是縮短函式。

• 歸屬和署名

  /* Added by Rick */

• 註釋掉的程式碼

  • 直接把程式碼註釋掉是討厭的作法，別這麼幹！

• HTML註釋

• 非本地資訊

  • 如果你一定要寫註釋，請確保它描述了離它最近的程式碼。
  • 別在本地註釋的上下文環境中給出系統級的資訊。

• 資訊過多

  • 別在註釋中新增有趣的歷史性話題或者無關的細節描述。

• 不明顯的聯絡

  • 註釋和其描述的程式碼之間的聯絡應該顯而易見。

• 函式頭

  • 短函式不需要太多的描述。
  • 為只做一件事的短函式選個好名字，通常比寫函式頭註釋要好！

參考文獻

[1] Robert C. Martin 著，韓磊 譯，《程式碼整潔之道》，北京：人民郵電出版社，2010.1（2018.9 重印), ISBN 978-7-115-21687-8。