从课程作业到可维护项目:MachiKoro 的重构与归档
项目代码:https://github.com/yicongl1/Machikoro
MachiKoro 最初是上海大学 2022 秋季「算法与编程」的课程项目。第一版能跑,但结构很粗糙;后来花了一轮时间做重构、补文档、留归档,才变成现在这个可以拿给别人看的样子。
这篇不谈具体规则,只谈“一个课程作业怎么收尾”。
第一版的问题
旧版原型还留在仓库的 archive/legacy-v0.1/ 里。它有几个典型问题:
Game同时负责规则、界面和输入,一个文件几千行- 购买流程用
int返回“金币数或卡槽号”,语义靠猜 - 卡牌、玩家对象全部
new出来,没有释放 - 输入混用
cin >>和getline(),偶尔读到空行 - 洗牌用
random_shuffle,随机源不可控 - 基类没有虚析构函数
这些问题在“能演示”的阶段都不致命,但一旦要改规则,就会一个接一个冒出来。
重构做了什么
不是重写,而是按风险从高到低逐个处理:
- 先修正确性:购买先校验后扣钱、紫卡重复判断、卡槽越界、紫卡触发条件、购物中心下标、体育场不向自己收钱。
- 再修输入:统一
getline(),加normalize()、parse_int()、EOF 处理。 - 然后修资源与未定义行为:
Card加虚析构、成员默认初始化、random_shuffle换成std::shuffle+std::mt19937。 - 最后整理结构:把购买流程的返回值改成
PurchaseCode,把 AI 的决策收敛成“合法候选集”,把重复的打印逻辑抽成函数。
每一步都保持“改完能编译、能跑一局”。课程项目没有测试框架,最怕的是一次改太多,最后不知道是哪一处改坏了。
为什么保留旧版和课程笔记
仓库里现在有几类“看起来没用”的东西:
archive/legacy-v0.1/:第一版源码archive/course-notes/课程笔记.docx:原始课程笔记docs/course-notes.md:整理后的 Markdown 笔记docs/uml/:类图(Visio 源文件 + PDF)docs/demo/:三段演示视频
它们不参与编译,但回答了几个以后一定会被问到的问题:
- 这个项目是怎么一步步变成现在这样的?
- 当时的设计意图是什么?
- 它真的能跑吗?
尤其是 UML。写代码的时候觉得类图是形式主义,等过几个月再回来看,类图比代码更快让人恢复上下文。
如果重做,我会怎么改
1. 拆开 Game / View / Controller
现在 Game 既算钱又打印菜单,还解析输入。理想的结构是:
Game/Rules:纯规则与状态,不依赖coutView:所有打印Controller:读输入、调用规则、更新视图
这样规则可以用单元测试直接驱动,不需要模拟控制台输入。
2. 用智能指针管理对象
卡牌和玩家目前都是裸 new,进程结束由操作系统回收。课程作业可以接受,但如果要做存档、回放、单元测试,就需要明确所有权。std::unique_ptr<Card> + std::vector<std::unique_ptr<...>> 是更合适的起点。
3. 卡牌数据化
15 种建筑的名字、价格、点数、图标、倍率现在散落在各个构造函数里。更可维护的做法是放一份 JSON/YAML:
- name: CheeseFactory
cost: 5
value: 3
roll: [7, 7]
color: green
multiplier: cow
代码只负责解释数据,新增卡牌不用重新编译。
4. 补单元测试
最值得测的是结算:
- 各种颜色、各种点数下的收付款
- 余额不足时
withdraw()的返回值 - 购物中心加成
- 紫卡的触发条件
- 购买失败时状态不变
这些测试不需要控制台,只需要 Game 暴露一个可注入的状态。
小结
课程作业通常止步于“演示时能跑”。但只要多花一点时间做三件事——修边界、留文档、存归档——它就能从一次交作业变成一个可以讲清楚的项目。
重构的价值也不在于用了多少设计模式,而在于让下一次修改的成本变低。对这个项目来说,最大的收获是:写规则的时候开始先想“这个状态会不会被破坏”,而不是先想“怎么让它跑起来”。
相关技能
- C++
- Git