Code Review

這份文件主要目的：

• 紀錄自己在工作中遇到難以理解的程式碼，並將其整理成較易閱讀的形式。

• 分享一些能縮短程式碼、提升可讀性的小技巧。

• 包含個人的一些寫作和開發習慣。

• 使用 JavaScript 作為範例，部分內容參考自《Clean Code》。

---

基本原則

• Component 結構：Component 最多不超過 3 層，保持結構單純易讀。

• 執行順序理解：先手寫流程想像圖，幫助理解程式碼的運作順序，寫完再對照實際結果。

• 開發前準備：

  • 與設計稿確認 UI 細節。

  • 與後端確認 API 介面格式。

  • 儘量在開發前把不確定的地方問清楚。

• Component 查找性：所有 UI 組件應能從 Page 下的 component 找到，避免出現「無法追溯來源」的孤立 component。

• 開發方式：優先使用「組合式開發」，減少繼承式（Inheritance）設計。

---

if 篇

條件過於複雜時

• 必須加上註解，解釋正在判斷什麼。

// 必須寫註解說明條件內容
if (conditionA && conditionB && conditionC) {
  // ...
}

條件明確展開

• 面對不同條件處理時，盡量展開每個條件，不要用單一 else 粗略帶過。

錯誤示範：

function example(type) {
  if (type === 1) {
    // ...
  } else if (type === 2 || type === 3) {
    // ...
  } else {
    // ...
  }
}

正確示範：

function example(type) {
  if (type === 1) {
    // ...
  } else if (type === 2 || type === 3) {
    // ...
  } else if (type === 4 || type === 5) {
    // ...
  }
}

補充：如果出現「不在條件範圍」的情況，不應該直接加一個 else 補救，應該思考「為什麼有異常的值進來」。

---

用物件替代條件判斷

• 當遇到「條件對應不同值」時，可以用 Map/Object 取代 if-else。

範例：

function sample(choose) {
  const map = {
    a: 1,
    b: 2,
  };

  return map.hasOwnProperty(choose) ? map[choose] : 0;
}

---

function 篇

只保留一個 return

• 一個 function 只應有一個出口，方便追蹤和除錯。

錯誤示範：

function example() {
  if (condition) {
    return 1;
  } else {
    return 2;
  }
}

正確示範：

function example() {
  let result = 2;
  if (condition) {
    result = 1;
  }
  return result;
}

---

避免傳遞旗標參數

• 儘量用 isXXX 命名讓變數有語意，而不是傳一堆 flag。

• 當參數太多 boolean 會讓 function 難以理解和維護。

避免傳遞 null 或 undefined

• 除非是 API response 必須接收，否則內部資料結構應避免出現 null / undefined。

• 避免造成額外的錯誤處理和程式混亂。

---

註解篇

• 複雜的邏輯必須加註解，說明「為什麼要這樣做」（不是「做了什麼」）。

• 遇到特殊情況、非預期結果時，要留下解釋。

• 盡量用清晰的命名和程式結構表達意圖，而不是依賴大量註解補救。

---

附加建議

命名規範

• 變數、函數名稱應能直接表達內容意圖。

• 函數名稱用動詞開頭，例如：getUser(), updateProfile(), sendRequest()。

• 物件名稱或資料結構用名詞，例如：userInfo, postList, appConfig。

---

小型函式

• 一個 function 控制的邏輯不超過 50 行，最好保持在螢幕一頁能閱讀完。

• 當 function 過大，應考慮切分成子 function，並清楚命名。

---

錯誤處理

• 主動處理錯誤情況，特別是 API 呼叫或非同步操作。

• 使用 try-catch，或者 promise 的 .catch()，讓錯誤容易追蹤。

• 在 catch 區塊中也要留下有意義的錯誤訊息。