<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "d0a02cb117e91a5b5f24178080068a3d",
  "translation_date": "2025-10-22T22:49:04+00:00",
  "source_file": "7-bank-project/3-data/assignment.md",
  "language_code": "mo"
}
-->
# 程式重構與文件撰寫作業

## 學習目標

完成此作業後，您將練習專業開發者每天使用的重要軟體開發技能。您將學習如何組織程式碼以提高可維護性、透過抽象化減少重複性，並為未來的開發者（包括您自己）撰寫文件。

乾淨且有良好文件的程式碼對於多位開發者合作以及隨時間演進的真實世界網頁開發專案至關重要。

## 作業概述

您的銀行應用程式的 `app.js` 文件已經隨著登入、註冊和儀表板功能的增加而變得相當龐大。現在是時候使用專業開發實踐來重構這段程式碼，以改善可讀性、可維護性並減少重複性。

## 指導說明

透過實施以下三個核心重構技術來改造您目前的 `app.js` 程式碼：

### 1. 提取配置常數

**任務**：在文件的頂部建立一個配置區域，包含可重複使用的常數。

**實作指導：**
- 提取目前在多個地方硬編碼的伺服器 API 基本 URL
- 為多個函數中出現的錯誤訊息建立常數
- 考慮提取多次使用的路徑和元素 ID

**範例結構：**
```javascript
// Configuration constants
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) {
  // Your implementation here
}
```


### 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) {
  // Prevent default form submission to handle with JavaScript
  event.preventDefault();
  
  // Your implementation...
}
```


## 成功標準

您的重構程式碼應展示以下專業開發實踐：

### 卓越實作
- ✅ **常數**：所有魔法字串和 URL 都被提取到清晰命名的常數中
- ✅ **DRY 原則**：常見的請求邏輯被整合到可重複使用的 `sendRequest()` 函數中
- ✅ **文件**：函數有清晰的 JSDoc 註解，解釋目的和參數
- ✅ **組織**：程式碼以區段標題和一致的格式進行邏輯分組
- ✅ **錯誤處理**：使用新的請求函數改進錯誤處理

### 基本實作
- ✅ **常數**：大多數重複值已被提取，僅剩少量硬編碼值
- ✅ **重構**：基本的 `sendRequest()` 函數已建立，但可能無法處理所有邊界情況
- ✅ **註解**：關鍵函數已記錄，但某些解釋可能不夠完整
- ✅ **可讀性**：程式碼大致上組織良好，但某些區域仍有改進空間

### 需要改進
- ❌ **常數**：許多魔法字串和 URL 仍然在文件中硬編碼
- ❌ **重複性**：類似函數之間仍存在大量程式碼重複
- ❌ **文件**：缺少或不充分的註解，未解釋程式碼的目的
- ❌ **組織**：程式碼缺乏清晰的結構和邏輯分組

## 測試您的重構程式碼

重構後，確保您的銀行應用程式仍然正常運作：

1. **測試所有使用者流程**：註冊、登入、儀表板顯示和錯誤處理
2. **驗證 API 呼叫**：確認您的 `sendRequest()` 函數在建立和檢索帳戶時正常運作
3. **檢查錯誤情境**：使用無效憑證和網路錯誤進行測試
4. **檢查控制台輸出**：確保重構過程中未引入新的錯誤

## 提交指南

提交您的重構後 `app.js` 文件，需包含：
- 使用區段標題組織不同功能
- 一致的程式碼格式和縮排
- 所有函數的完整 JSDoc 文件
- 文件頂部簡短的註解，解釋您的重構方法

**額外挑戰**：建立一個簡單的程式碼文件文件 (`CODE_STRUCTURE.md`)，解釋您的應用程式架構以及不同函數如何協同工作。

## 真實世界連結

此作業模擬專業開發者定期執行的程式碼維護工作。在業界環境中：
- **程式碼審查** 會像此作業一樣評估可讀性和可維護性
- **技術債務** 會因未定期重構和撰寫文件而累積
- **團隊合作** 依賴於清晰且有文件的程式碼，讓新成員能夠快速理解
- **錯誤修復** 在具有良好組織和適當抽象的程式碼庫中更容易進行

您在此處練習的技能——提取常數、消除重複性以及撰寫清晰的文件——是專業軟體開發的基礎。

---

**免責聲明**：  
本文件已使用 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。雖然我們致力於提供準確的翻譯，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件的母語版本應被視為權威來源。對於關鍵信息，建議使用專業人工翻譯。我們對因使用此翻譯而產生的任何誤解或誤釋不承擔責任。