|
|
# 程式碼重構與文件撰寫作業
|
|
|
|
|
|
## 學習目標
|
|
|
|
|
|
完成此作業後，您將練習專業開發人員每日使用的重要軟體開發技能。您將學會組織程式碼以利於維護，透過抽象化減少重複，並為未來的開發者（包括您自己）撰寫文件。
|
|
|
|
|
|
乾淨且良好記錄的程式碼對於多位開發者協作且程式碼庫隨時間演進的真實網頁開發專案至關重要。
|
|
|
|
|
|
## 作業概述
|
|
|
|
|
|
您的銀行應用程式的 `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`，說明您的應用架構及各函式如何協同運作。
|
|
|
|
|
|
## 真實世界關聯
|
|
|
|
|
|
此作業模擬專業開發人員經常進行的程式碼維護工作。在業界：
|
|
|
- **程式碼審查** 會評估可讀性與維護性，類似此作業
|
|
|
- **技術債務** 若未定期重構與文件記錄就會累積
|
|
|
- **團隊協作** 依賴清晰且良好記錄的程式碼，方便新成員理解
|
|
|
- **錯誤修復** 在有妥善抽象與組織的程式碼庫中更為容易
|
|
|
|
|
|
您此處練習的技能──擷取常數、消除重複與撰寫清楚文件──是專業軟體開發的基本功。
|
|
|
|
|
|
---
|
|
|
|
|
|
<!-- CO-OP TRANSLATOR DISCLAIMER START -->
|
|
|
**免責聲明**：
|
|
|
本文件由 AI 翻譯服務 [Co-op Translator](https://github.com/Azure/co-op-translator) 進行翻譯。儘管我們力求準確，但請注意，自動翻譯可能包含錯誤或不準確之處。原始文件之母語版本應視為權威來源。對於重要資訊，建議聘請專業人工翻譯。我們不對因使用本翻譯而產生的任何誤解或曲解負責。
|
|
|
<!-- CO-OP TRANSLATOR DISCLAIMER END --> |
