port-from-reference

name	port-from-reference
description	从参考代码移植功能时的铁律。Use when: 照着参考文档/参考项目实现功能、移植赛题逻辑、参照已有代码写新模块。核心原则：先忠实翻译跑通，再优化；禁止预加防御逻辑。

参考代码移植铁律

一条铁律

先照着参考代码一字不差地翻译实现，跑通了再往上加东西。不要自己发明"防御逻辑"。

反面教材

参考代码 Q1 就三行：

while (全白) { pid_angle(0°, yaw); motor_run(); }
停车; 蜂鸣;

被我翻译成了：

• 加了 q1_startup（启动跳5帧）
• 加了 q1_line_cnt（连续3帧确认）
• 加了 q1_beep_cnt（蜂鸣节奏控制）
• 三层 if-else 嵌套
• 结果：原始逻辑被埋在一堆防御代码里，跑都跑不通

正确做法

1. 第一步：把参考代码逐行翻译成当前项目的 API 风格，结构完全一致
2. 第二步：编译烧录，确认基本功能跑通
3. 第三步：根据实测问题，一次只加一个优化（如：发现误触发 → 加防抖；发现停车后抖动 → 加 PID 清零）
4. 不要：预判可能有什么问题就提前加代码——你没跑过怎么知道会不会出问题？

判断标准

移植完问自己：删掉注释，代码行数和参考代码是不是差不多？ 如果多出一倍以上，说明又犯了老毛病。

适用场景

• 照着 移植代码相关/ 里的参考文档实现功能
• 照着参考项目的 main.c 移植状态机
• 任何"参考已有实现写新代码"的场景