代碼整潔之道讀書記

有意義的命名

軟件編程中命名隨處可見, 如函數, 參數, 類名, 變量, 包名, 文件名等。一個好的命名可以望名知意, 方便後續的維護。

下面是一些基本的關於命名的規則:

• 命名語意化: 有意義的命名可以替代註釋

• 避免誤導性命名

  1. 命名外形上的類似
  如 數字0與字母O同時出現   變量xyzControllerForOrderOfSetting和xyzControllerForLoginSetting(須要花時間去區分)
  
  2. 語義廢話,含混不清的命名
  如 同一個模塊出現這樣的方法或者命名(須要花時間去區分). getUserInfo/getUserData/getUser, userInfo/userData/user
  
  複製代碼

• 多使用可以讀的出來的名稱: 避免自造詞, 多使用合乎規範的英文單詞

• 使用易搜索的名稱

  1. 易搜索指的是在海量代碼中快速定位到該命名
  2. 以單個字母命名的名稱僅適用於短方法中的本地變量(如js中d(document),w(window))
  3. 命名的長短應該與做用域大小成對應關係
  複製代碼

• 類名

  類名與對象名應該是名詞或者名詞短語, 避免使用Processor, UserData等,類名不該該是動詞
  複製代碼

• 方法名

  方法名應該是動詞或者動詞短語
  屬性訪問器,屬性修改器,斷言等應該加上get, set, is等前綴
  複製代碼

• 每一個概念對應一個詞, 而且一以貫之

  舉例說明:
  好比你在一個類裏面的同類型方法都是使用get做爲前綴, 可是在另一個類裏面的方法又是使用fetch做爲前綴。這就是沒有保持一個概念一個詞。
  
  另外就是保持你的代碼風格統一性
  複製代碼

• 避免使用雙關語

  避免同一個單詞用於不一樣的目的，同一個術語用於不一樣的概念
  複製代碼

• 多使用你們達成統一認識的領域名稱(術語)

  舉例說明
  好比使用visitor(訪問者)而不是accounrVistor
  Queue/jobQueue
  複製代碼

• 添加有意義的語境

  大多數時候咱們是無法經過命名達到自我說明, 這個時候就須要添加適當的語境來方便咱們理解。
  添加語境的方式就是給命名添加前綴。
  createXxxx / addXxx / deleteXxx / updateXxx
  複製代碼

• 避免添加無心義的語境

  當短名稱足夠描述清楚時候, 要優於長名稱
  複製代碼

  如何寫好函數

• 短小

  函數應該短小，不能太長, 20行封頂
  複製代碼

• 代碼塊和縮進

  if語句,else語句,while語句,switch/case中子句等, 其中的代碼塊應該只有一行,該行也應該是一個函數調用語句。
  例如：
  if (true) {
      // 函數調用
  } else {
      // 函數調用
  }
  複製代碼

• 一個函數應該只作一件事

  當你的函數不能再被拆開一個函數時候就標示作了一件事
  複製代碼

• 一個函數一個抽象層級(抽象邏輯塊)

  代碼應該保持一個自頂向下的閱讀順序。
  每個函數後面儘量緊跟下一個抽象層級的函數
  複製代碼

• switch語句

  switch/case語句有多個子句時候，能夠把switch語句置於抽象工廠中，不對外暴露,而後工廠方法中針對不一樣的case語句建立不一樣的實體
  複製代碼

• 使用描述性的名稱

• 函數參數

  1. 函數參數個數: 理想狀況函數參數個數依次爲0,1,2,超過兩個應該避免
  2. 當函數須要三個或者超過三個以上參數時候, 推薦把一些對象封裝爲類
  3. 當咱們須要傳入個數可變的參數時候, 可使用參數列表
  
  複製代碼

• 動詞與關鍵詞結合

• 對於一元函數時候, 咱們可使用動詞與關鍵詞結果方式來更好表述該函數的做用。
  舉例:
  writeField(name): => 修改字段name
  複製代碼

• 無反作用

  雖然咱們說函數只作一件事, 可是經常會隱式的作一些其餘事情,致使異常的發生, 尤爲像動態語言(Python,JavaScipt), 沒有類型約束, 一不當心就修改了對象類型。
  
  避免使用輸出參數, 若是參數必需要修改某種狀態，索性就修改所屬對象的狀態
  複製代碼

• 分隔指令與詢問

  函數要麼作什麼事情，要麼回答什麼事情，二者不可兼得。即
  函數要麼修改某對象的狀態, 要麼返回該對象的有關信息
  複製代碼

• 使用異常替代返回錯誤碼

  舉例:
  一個函數deletePage(page)用錯誤碼標示執行的結果: E_OK / E_ERROR
  若是你的代碼中大量採用該風格的函數, 有時候會致使大量的if嵌套。
  
  if (deletePage(page) == E_OK) {
      if (deletePerson(person) == E_OK) {
          
      } else {
          
      }
  } else {
      
  }
  
  咱們應該使用異常替代返回錯誤碼的方式，這樣錯誤處理代碼就能把代碼進行分離
  
  try (
  	// 主路徑代碼
  ) catch () {
      // 錯誤處理
  }
  複製代碼

• 抽離try/catch代碼塊

  函數應該只作一件事, 錯誤處理就是一件事 
  複製代碼

• DRY原則: 別重複本身

  消除重複 => 提取代碼中能複用的模塊, 複用的類, 複用的方法等
  複製代碼

註釋

與其給糟糕的代碼添加註釋不如重寫
複製代碼

註釋最大的隱患在於隨着存在時間越久, 距離其所描述的代碼越遠, 因此對於程序員來講,應該時刻保持註釋與代碼的同步。

• 註釋不能美化糟糕的代碼

  與其爲糟糕的,難以理解的代碼寫註釋不如花時間重寫代碼
  複製代碼

• 用代碼來替代註釋闡述內容

• 好註釋

  1. 提供信息的註釋: 好比文件註釋, 類註釋, 函數註釋等
  2. 闡述: 當咱們沒法經過參數或者返回值來描述代碼內容時候須要經過註釋來描述
  3. 警示類註釋: 提醒後面維護者可能出現的結果
  4. TODO註釋: 描述你將來要作的工做列表
  5. 編寫公共的api註釋文檔
  複製代碼

• 壞註釋

  1. 多餘的註釋: 沒法提供比代碼自己提供更多的信息, 或者說讀註釋並不比讀代碼效果好
  2. 誤導性註釋: 你的註釋不夠精確, 甚至自己就有錯誤
  3. 循規式註釋(這個仁者見仁智者見智): 做者以java爲例每一個函數都要有javadoc是不可取的,pyhon其實也有文檔字符串的約定
  4. 日誌式註釋: 記錄代碼變動或者代碼log等
  複製代碼

• 對於再也不須要的註釋直接刪除而不是原地註釋掉, 會對後續維護者產生誤導