计算机科学与技术 王阿丽亚·阿不来海提 3223004639
计算机科学与技术 阿依古再丽·艾力 3223004595
| 这个作业属于哪个课程 | https://edu.cnblogs.com/campus/gdgy/Class34Grade23ComputerScience | |
|---|---|---|
| 这个作业要求在哪里 | https://edu.cnblogs.com/campus/gdgy/Class34Grade23ComputerScience/homework/13477 | |
| 这个作业目标 | 实现一个自动生成小学四则运算题目的命令行程序 |
PSP表格相关记录
| PSP2 1 | Personal Software Process Stages | 预估耗时（分钟） | 实际耗时（分钟） |
|---|---|---|---|
| Planning | 计划 | 30 | 30 |
| Estimate | 估计这个任务需要多少时间 | 615 | 605 |
| Development | 开发 | 15 | 15 |
| Analysis | 需求分析（包括学习新技术） | 60 | 90 |
| Design Spec | 生成设计文档 | 20 | 10 |
| Design Review | 设计复审 | 30 | 15 |
| Coding Standard | 代码规范（为目前的开发制定合适的规范） | 30 | 30 |
| Design | 具体设计 | 60 | 60 |
| Coding | 具体编码 | 240 | 240 |
| Code Review | 代码复审 | 10 | 10 |
| Test | 测试（自我测试，修改代码，提交修改） | 30 | 40 |
| Reporting | 报告 | 15 | 15 |
| Test Report | 测试报告 | 15 | 15 |
| Size Measurement | 计算工作量 | 30 | 15 |
| Postmortem & Process Improvement Plan | 事后总结，并提出过程改进计划 | 30 | 20 |
模块接口的设计与实现过程
总体说明
目标：生成小学四则运算题目、解析与计算表达式、并对用户答案进行判题与评分。各模块职责清晰，尽量使用 Fraction 类型保证精度。
公共约定：表达式树使用 tuple 结构 (op, left, right) 或 Fraction/int 作为叶子。所有 I/O 操作（读写文件）封装成可能抛出 FileOperationError 的高层 API。
解析/计算失败使用领域异常：ExpressionParseError、RuleViolationError、ParameterValidationError 等。
- errors.py — 异常模块
目的：定义域内自定义异常类型，统一错误处理接口。
公共类型（接口）： - CalculatorError(Exception) — 基类。
- RuleViolationError(CalculatorError) — 规则校验失败（如生成题目时出现负数、不合法分数等）。
- ExpressionParseError(CalculatorError) — 解析表达式失败，构造器允许传入 message 与 text（原始文本）。
- FileOperationError(CalculatorError) — 封装文件 I/O 错误，构造器接受 message 和可选 path 字段。
- ParameterValidationError(CalculatorError) — 输入参数验证失败。
- utils.py — 工具库
主要职责：
格式化与解析分数（format_fraction, parse_fraction）。
将表达式树正规化用于去重（normalize_expr）。
表达式词法与语法解析：tokenize、parse_expression（返回表达式树）。
基础分数算术封装（fraction_add/sub/mul/div）与便利函数 is_proper_fraction。
主要函数摘要
- format_fraction(frac: Fraction|int) -> str
描述：把 Fraction 格式化为字符串，真分数显示为 "a'b/c" 或 "num/den" 或整数。
错误模式：接受可转为 Fraction 的对象；不会抛错，除非传入非法类型（会在调用处报错）。 - parse_fraction(s: str) -> Fraction
描述：解析字符串到 Fraction，支持 "2'3/5"、"3/5"、"2"。
错误模式：无法解析时抛 ExpressionParseError（含原文本）。 - tokenize(expr: str) -> iterator[(kind, token)]
描述：词法化；在遇到无法识别字符时抛 ExpressionParseError，提供位置信息。 - parse_expression(s: str) -> expr_tree
描述：基于递归下降解析实现，返回表达式树（tuple 或 Fraction/int）。
错误模式：遇到语法错误抛 ExpressionParseError；接口保证在输入合法时返回可交给 eval_expr 的树。 - normalize_expr(expr) -> str
描述：把表达式树归一化为字符串键，支持 + 和 × 的交换律（将子项排序）。
用途：用于题目去重集合的判定。 - generator.py— 题目生成模块
主要职责：
随机生成题目表达式树（random_expr、random_number）。
计算表达式值（eval_expr）。
将表达式转换为字符串（expr_to_str）。
批量生成并写入文件（generate(n, r) -> writes Exercises.txt & Answers.txt）。
接口契约（函数签名）： - random_number(r: int) -> int|Fraction
行为：以50%概率返回自然数或真分数，范围基于 r。
错误模式：假定 r 为 int 且 r > 1。 - random_expr(r: int, max_ops: int=3) -> expr_tree
描述：递归生成表达式树，max_ops 控制运算符数量。 - eval_expr(expr) -> Fraction
描述：递归计算表达式树的 Fraction 结果；在非法数学情况时抛 ValueError（负数、除以0、非真分数结果等）。 - expr_to_str(expr) -> str
描述：把表达式树转换为文本形式（带括号），叶子用 format_fraction 格式化。 - generate(n: int, r: int) -> None
描述：生成 n 道题并写入 Exercises.txt 与 Answers.txt，过程进行参数验证、去重（normalize_expr）、规则校验（捕获 RuleViolationError）及 I/O 错误封装为FileOperationError。
输出/副作用：在控制台打印生成数量；在异常情况下抛出 FileOperationError 或 ParameterValidationError。
边界情况与错误模式：
参数验证：n 必须为正 int，r 必须大于 1（否则抛 ParameterValidationError）。
生成失败：在多次尝试后仍未生成足够题目，函数当前只是结束并写入已生成的题目；可增强以在不足时抛自定义异常或返回状态。
数学规则：eval_expr 对减法、除法结果做严格检查（例如不允许负数和非真分数），并抛 ValueError；这被 generator 捕获并跳过该表达式。
grader.py — 判题模块
主要职责：
读取题目文件与用户答案文件，解析题目文本为表达式树，计算标准答案，比较用户答案并把统计写回 [Grade.txt](vscode-file://vscode-app/d:/Microsoft VS Code/resources/app/out/vs/code/electron-browser/workbench/workbench.html)。
公共接口
grade(exercise_file: str, answer_file: str) -> None
输入：exercise_file（路径），answer_file（路径）
行为：读取两文件、逐行解析表达式、计算标准值、解析用户答案（parse_fraction），比对并分类到 correct/wrong、最后写 [Grade.txt](vscode-file://vscode-app/d:/Microsoft VS Code/resources/app/out/vs/code/electron-browser/workbench/workbench.html)。
错误模式：文件读写失败抛 FileOperationError；解析失败会将该题计为 wrong，并在日志中记录 debug；在极端未处理异常时捕获并记录，继续判题以保证输出。
边界情况
文件行数不匹配：如果 user_answers 更短，后续题目不会被判分（未处理）。
解析差异：若表达式解析成功但 eval_expr 抛异常，当前会被 broad except 捕获并计为 wrong（并输出到控制台）。
数据形状与示例
表达式树示例：
5 -> int or Fraction(5,1)
( '+', 1, 2 ) -> 表示 1 + 2
( '×', ( '+', 1, 2 ), 3 ) -> (1+2)×3
normalize_expr 返回例如 "+(1/2,3/4)" 用于集合去重。
generate 输出文件格式
Exercises.txt的行： "1/2 + 3 ="
Answers.txt 的行： "7/2" 或 "3'1/2"（由 format_fraction 产生）
Grade.txt
格式
Correct: (list)
Wrong: (list)
错误与异常模型（总结）
-
低层（解析/数学）：
ExpressionParseError（解析问题）
ValueError（当前用于数学约束，如负数、除零） -
中层（生成/判题）：
RuleViolationError（生成时违反表达式规则）
ParameterValidationError（非法参数） -
高层（I/O）：
FileOperationError（读写失败，包含 path） -
规则检查处理
目标：检查数学运算中不符合题目规则要求的情况（如除以零、减法产生负值、除法结果不是真分数等）。
对应代码片段：
def truediv(self, other: 'FractionNumber') -> 'FractionNumber': # 除零异常检查
if other.numerator == 0: # 检查是否存在除数为零的情况
raise ZeroDivisionError("Cannot divide by zero.")
new_num = self.numerator * other.denominator
new_den = self.denominator * other.numerator
return FractionNumber(new_num, new_den)
def sub(self, other: 'FractionNumber') -> 'FractionNumber': # 减法结果负值异常检查
new_num = self.numerator * other.denominator - other.numerator * self.denominator
new_den = self.denominator * other.denominator
return FractionNumber(new_num, new_den)
elif self.op == '-': # 检查是否存在e1 < e2的情况
if l.value() < r.value():
raise ValueError("Subtraction would result in negative.")
return l - r
def is_proper_fraction(fraction: FractionNumber) -> bool: # 真分数约束检查
return abs(fraction.numerator) < fraction.denominator and fraction.denominator > 1
if op == '/': # 在除法运算后的验证
res = l / r # 严格检查除法结果是否为真分数
if not is_proper_fraction(res):
raise ValueError("Division result must be a proper fraction...")
- 表达式解析异常处理
目标：处理用户输入表达式格式错误或求值错误（语法错误、非法字符、运算异常等）。
对应代码片段：
def evaluate_expression(expression: str) -> FractionNumber:
expr_processed = preprocess_expression(expression)
try:
result = eval(expr_processed)
except Exception as e:
raise ValueError(f"表达式求值失败：{e}")
if isinstance(result, Fraction): # 类型检查
return FractionNumber(int(result.numerator), int(result.denominator))
elif isinstance(result, int):
return FractionNumber(result, 1)
else:
raise ValueError(f"无法识别的计算结果类型：{type(result)}")
- 文件操作异常处理
目标：确保文件读写操作的可靠性并在异常时给出明确提示或回退。
对应代码片段：
def compare_answers(exercise_file: str, answer_file: str):
try:
with open(exercise_file, 'r', encoding='utf-8') as f:
exercises = f.readlines()
with open(answer_file, 'r', encoding='utf-8') as f:
answers = f.readlines()
if len(exercises) != len(answers):
print(f"❌ 错误：题目数量({len(exercises)}) 与答案数量({len(answers)}) 不相等。")
return
except Exception as e:
print(f"批改时发生错误：{e}")
- 题目生成重试机制
目标：处理生成过程中的临时错误和不满足规则的情况，确保最终输出满足约束或在失败时以明确方式终止。
对应代码片段：
def generate_expression(r: int, max_ops: int = MAX_OPERATORS) -> Tuple[str, FractionNumber, str]:
num_tries = 0
max_tries = 1000
while num_tries < max_tries:
num_tries += 1
try: # 生成逻辑
return expr_str, val, structure_hash
except Exception as e:
continue # 静默重试
raise RuntimeError("Failed to generate valid expression after many tries.")
- 参数验证异常
目标：确保程序入口输入参数合法，避免下游函数收到非法参数导致难以排查的错误。
对应代码片段：
def main(): # 参数解析
if r < 1:
print("❌ 错误：-r 后的数值范围必须 >= 1，例如：-r 10")
return
except ValueError:
print("❌ 错误：-n 后必须跟一个整数，表示题目数量。例如：-n 10")
return
项目总结
通过本次结对编程项目，我们圆满实现了需求规格中的所有功能要求，并在合作过程中获得了显著的成长与收获。在项目成果方面，结对编程模式有效提升了我们的代码质量。通过实时代码审查和深入讨论，我们成功减少了因疏忽导致的低级错误。特别是在分数运算和表达式生成等复杂功能的实现过程中，持续的头脑风暴和即时反馈帮助我们攻克了多个技术难点，确保了项目的顺利推进。在个人成长与团队协作方面，这次合作为我们创造了宝贵的相互学习机会。团队成员各展所长：一位成员在编码实现和调试方面表现出色，能够熟练运用调试工具进行性能分析，快速定位问题根源；另一位成员则展现了优秀的架构设计能力，善于从整体角度规划代码结构，避免陷入细节陷阱，同时在调试复杂逻辑时展现出极大的耐心和细致。这种优势互补的合作模式，特别是在代码规范和模块化设计方面的深入交流，为我们后续的项目开发奠定了坚实基础。通过项目复盘，我们也认识到在逻辑严谨性方面仍有提升空间，代码问题的排查效率可以进一步优化。展望未来的项目开发，我们计划更系统地采用测试驱动开发方法，并建立更完善的调试流程，以持续提升代码质量。