# Code Review

這份文件主要目的：

* 紀錄自己在工作中遇到難以理解的程式碼，並將其整理成較易閱讀的形式。
* 分享一些能縮短程式碼、提升可讀性的小技巧。
* 包含個人的一些寫作和開發習慣。
* 使用 JavaScript 作為範例，部分內容參考自《Clean Code》。

***

### 基本原則

* **Component 結構**：Component 最多不超過 3 層，保持結構單純易讀。
* **執行順序理解**：先手寫流程想像圖，幫助理解程式碼的運作順序，寫完再對照實際結果。
* **開發前準備**：
  * 與設計稿確認 UI 細節。
  * 與後端確認 API 介面格式。
  * 儘量在開發前把不確定的地方問清楚。
* **Component 查找性**：所有 UI 組件應能從 `Page` 下的 component 找到，避免出現「無法追溯來源」的孤立 component。
* **開發方式**：優先使用「組合式開發」，減少繼承式（Inheritance）設計。

***

### if 篇

#### 條件過於複雜時

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

```javascript
// 必須寫註解說明條件內容
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 區塊中也要留下有意義的錯誤訊息。
