|
|
# 代码重构与文档作业
|
|
|
|
|
|
## 学习目标
|
|
|
|
|
|
完成本作业后，您将练习专业开发人员每天使用的关键软件开发技能。您将学习如何组织代码以便于维护，通过抽象减少重复，并为未来的开发者（包括您自己）编写文档。
|
|
|
|
|
|
干净且有良好文档的代码对于现实世界中多个开发者协作和代码库持续发展的 Web 开发项目至关重要。
|
|
|
|
|
|
## 作业概述
|
|
|
|
|
|
您的银行应用中的 `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. 添加专业代码文档
|
|
|
|
|
|
**任务**：用清晰、实用的注释为代码编写文档，解释逻辑背后的“为什么”。
|
|
|
|
|
|
**文档标准：**
|
|
|
- 为函数添加说明，解释用途、参数和返回值
|
|
|
- 为复杂逻辑或业务规则添加内联注释
|
|
|
- 用分节标题将相关函数归组
|
|
|
- 解释任何非显而易见的代码模式或浏览器特定的 workaround
|
|
|
|
|
|
**示例文档风格：**
|
|
|
```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 --> |
