# 代碼重構與文件編寫作業

## 學習目標

完成此作業後，您將練習專業開發者日常使用的關鍵軟體開發技能。您將學會如何組織代碼以維護性為主、透過抽象減少重複，並為未來的開發者（包括您自己）撰寫文件說明。

乾淨且具備良好文件說明的代碼，對於多位開發者協作且代碼庫隨時間演進的真實網頁開發專案至關重要。

## 作業概述

您的銀行應用程式中的 `app.js` 檔案已隨著登入、註冊與儀表板功能大幅成長。現在是時候使用專業開發實務來重構這份代碼，以提升可讀性、可維護性，並減少冗餘代碼。

## 指示

請透過實作以下三個核心重構技巧，轉換您目前的 `app.js` 程式碼：

### 1. 抽取設定常數

**任務**：在檔案頂部建立一個配置區段，包含可重用的常數。

**實作建議：**
- 抽取目前多處硬編碼的伺服器 API 基底 URL
- 建立多個函式中出現的錯誤訊息常數
- 考慮抽取多次使用的路由路徑與元素 ID

**示範架構：**
```javascript
// 配置常數
const API_BASE_URL = 'http://localhost:5000/api';
const ROUTES = {
  LOGIN: '/login',
  DASHBOARD: '/dashboard'
};
```

### 2. 建立統一的請求函式

**任務**：建置一個可重用的 `sendRequest()` 函式，消除 `createAccount()` 與 `getAccount()` 之間的重複代碼。

**需求：**
- 支援 GET 與 POST 請求
- 包含完善的錯誤處理
- 支援不同的 URL 端點
- 接受可選的請求主體資料

**函式簽名建議：**
```javascript
async function sendRequest(endpoint, method = 'GET', data = null) {
  // 你嘅實現寫喺度
}
```

### 3. 加入專業程式碼文件說明

**任務**：使用清楚且有助於理解邏輯「為什麼」的註解對代碼進行說明。

**文件說明標準：**
- 為函式加入說明目的、參數和回傳值的文件注釋
- 對複雜邏輯或商業規則添加內聯註解
- 使用區塊標題將相關函式組織在一起
- 解釋任何不明顯的程式樣式或瀏覽器特有的應變措施

**文件說明示範風格：**
```javascript
/**
 * Authenticates user and redirects to dashboard
 * @param {Event} event - Form submission event
 * @returns {Promise<void>} - Resolves when login process completes
 */
async function login(event) {
  // 防止預設表單提交，以便使用 JavaScript 處理
  event.preventDefault();
  
  // 你的實作方式…
}
```

## 成功標準

您的重構代碼應展現以下專業開發實務：

### 優異實作
- ✅ **常數**：所有魔術字串與 URL 均已抽取為清楚命名的常數
- ✅ **DRY 原則**：共用請求邏輯整合成可重用的 `sendRequest()` 函式
- ✅ **文件說明**：函式包含明確的 JSDoc 注釋說明目的與參數
- ✅ **組織架構**：利用區塊標題及一致的格式化對代碼進行合理分組
- ✅ **錯誤處理**：利用新請求函式強化錯誤處理機制

### 足夠實作
- ✅ **常數**：大部分重複值已抽取，僅有少量硬編碼殘留
- ✅ **因式分解**：基本的 `sendRequest()` 函式已建立，但可能未涵蓋所有邊界狀況
- ✅ **註解**：主要函式已註解，但有些說明尚可更完整
- ✅ **可讀性**：代碼整體組織良好，但仍有待改進之處

### 需加強
- ❌ **常數**：大量魔術字串與 URL 仍散佈於檔案中未抽取
- ❌ **重複**：類似函式間仍有明顯重複代碼
- ❌ **文件說明**：缺少或不足的註解，未能有效說明程式碼功能
- ❌ **組織架構**：代碼缺乏明確結構與邏輯分組

## 測試您的重構代碼

重構完成後，請確認您的銀行應用程式仍能正常運作：

1. **測試所有使用者流程**：註冊、登入、儀表板顯示及錯誤處理
2. **驗證 API 呼叫**：確認 `sendRequest()` 可同時用於帳戶建立與查詢
3. **檢查錯誤情境**：使用無效憑證及模擬網路錯誤測試
4. **檢視主控台輸出**：確保重構過程未新增新的錯誤訊息

## 提交指引

提交您的重構後的 `app.js` 檔案，應包含：
- 清楚的區段標題組織不同功能
- 一致的代碼格式與縮排
- 完整的 JSDoc 文件說明所有函式
- 頂部附簡短註解說明您的重構思路

**額外挑戰**：建立一個簡單的代碼文件（`CODE_STRUCTURE.md`），說明您的應用架構及各函式如何協同運作。

## 與真實世界的連結

此作業模擬專業開發者定期進行的代碼維護工作。在業界環境中：
- **代碼審查**會像此作業一樣評估可讀性與可維護性
- **技術債務**避免因未定期重構與文件產生
- **團隊協作**仰賴清楚且具良好文件的代碼令新成員能快速理解
- **Bug 修復**在有良好抽象與組織的代碼庫中更為容易

您在本次練習中培養的技能──抽取常數、消除重複、撰寫清晰文件──是專業軟體開發的基礎。

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**免責聲明**：  
本文件係使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 翻譯而成。我們致力確保翻譯準確，但請注意，自動翻譯可能包含錯誤或不準確之處。原文文件應視為權威依據。對於重要資訊，建議諮詢專業人工翻譯。本公司對於因使用本翻譯而引致的任何誤解或誤譯概不負責。
<!-- CO-OP TRANSLATOR DISCLAIMER END -->