项目代码:https://github.com/yicongl1/Machikoro

MachiKoro 最初是上海大学 2022 秋季「算法与编程」的课程项目。第一版能跑,但结构很粗糙;后来花了一轮时间做重构、补文档、留归档,才变成现在这个可以拿给别人看的样子。

这篇不谈具体规则,只谈“一个课程作业怎么收尾”。

第一版的问题

旧版原型还留在仓库的 archive/legacy-v0.1/ 里。它有几个典型问题:

  • Game 同时负责规则、界面和输入,一个文件几千行
  • 购买流程用 int 返回“金币数或卡槽号”,语义靠猜
  • 卡牌、玩家对象全部 new 出来,没有释放
  • 输入混用 cin >> 和 getline(),偶尔读到空行
  • 洗牌用 random_shuffle,随机源不可控
  • 基类没有虚析构函数

这些问题在“能演示”的阶段都不致命,但一旦要改规则,就会一个接一个冒出来。

重构做了什么

不是重写,而是按风险从高到低逐个处理:

  1. 先修正确性:购买先校验后扣钱、紫卡重复判断、卡槽越界、紫卡触发条件、购物中心下标、体育场不向自己收钱。
  2. 再修输入:统一 getline(),加 normalize()、parse_int()、EOF 处理。
  3. 然后修资源与未定义行为:Card 加虚析构、成员默认初始化、random_shuffle 换成 std::shuffle + std::mt19937。
  4. 最后整理结构:把购买流程的返回值改成 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:纯规则与状态,不依赖 cout
  • View:所有打印
  • 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 暴露一个可注入的状态。

小结

课程作业通常止步于“演示时能跑”。但只要多花一点时间做三件事——修边界、留文档、存归档——它就能从一次交作业变成一个可以讲清楚的项目。

重构的价值也不在于用了多少设计模式,而在于让下一次修改的成本变低。对这个项目来说,最大的收获是:写规则的时候开始先想“这个状态会不会被破坏”,而不是先想“怎么让它跑起来”。