🔴 五个原罪

🔴 原罪一：资源受限导致架构退化

⭐ 核心问题

随着功能不断增加，有限的 RAM/Flash资源 迫使开发者不断妥协，逐渐破坏原有架构。

🟠 典型现象

• 压缩结构体

• 复用全局变量

• 合并状态机

• 删除抽象层

🔴 后果

• 模块耦合严重

• 代码难理解

• Bug难定位

• 可维护性下降

⭐ 一句话总结

为了节省资源不断牺牲架构设计，最终导致系统难以维护。

---

🔴 原罪二：调试反馈链路过长

⭐ 核心问题

嵌入式调试周期长，验证成本高，工程师更容易采用经验修复而非定位根因。

🟠 典型现象

增加延时

HAL_Delay(500);

增加重试机制

for(int i = 0; i < 3; i++)
{
    if(UART_Send() == OK)
        break;
}

添加特殊判断

if(customer_type == CUSTOMER_A)
{
    return;
}

🔴 后果

• 补丁代码不断堆积

• 历史代码无人敢删

• 技术债务持续增加

⭐ 一句话总结

验证成本高 → 猜测式修复 → 补丁堆积 → 可维护性下降

---

🔴 原罪三：状态管理失控

⭐ 核心问题

多个任务、中断、回调共同修改全局状态变量，形成复杂状态耦合。

🟠 典型现象

volatile uint8_t g_system_state;
volatile uint8_t g_charging_flag;
volatile uint8_t g_ble_connected;

多个模块同时读写。

🔴 后果

• 状态像蜘蛛网

• 时序像迷宫

• Bug难复现

• 单测难覆盖

• Bug难定位

⭐ 一句话总结

全局状态缺乏统一管理，最终导致状态耦合和时序问题失控。

---

🔴 原罪四：工具链与文档衰变

⭐ 核心问题

项目寿命远长于开发工具和文档寿命。

🟠 典型现象

License丢失

源码还在
工程还在
↓
编译器无法激活
↓
无法编译

Wiki链接失效

旧文档链接
↓
知识库迁移
↓
404 Not Found

SDK停止维护

项目被锁死在旧版本SDK

🔴 后果

• 编译环境无法复现

• 历史设计无法追溯

• 新人接手困难

• 项目逐渐变成黑盒

⭐ 项目变成黑盒

代码能运行
↓
没人知道为什么这样写
↓
没人敢修改

⭐ 一句话总结

工具链会过时，文档会失效，知识会流失。

---

🟢 改进原则

🟢 原则一：记录“为什么”，而不是“是什么”

❌ Bad

HAL_Delay(500); // 延时500ms

✅ Good

// 等待SPI Flash上电稳定
// 规格书要求≥200ms
// 实测部分批次需约400ms
HAL_Delay(500);

⭐ 核心思想

记录：

为什么这样写

而不是：

代码做了什么

⭐ 一句话总结

记录设计决策，而不仅仅是代码行为。

---

🟢 原则二：建立唯一状态源（Single Source of Truth）

❌ 错误做法

g_state = STATE_RUN;
g_state = STATE_ERROR;

任何地方都能修改状态。

---

✅ 推荐做法

void sys_state_set(sys_state_t s, const char* who)
{
    LOG_DEBUG("state: %s -> %s by %s",
              state_name(g_state),
              state_name(s),
              who);

    g_state = s;
}

⭐ 优点

• 状态统一管理

• 记录状态变化

• 记录修改来源

• 便于问题追溯

⭐ 一句话总结

所有状态修改必须经过统一入口。

---

🟢 原则三：固化编译环境

⭐ 保存内容

• 编译器

• License

• SDK

• 构建脚本

• 后处理脚本

⭐ 常见方案

• 虚拟机（VMware）

• Docker容器

⭐ 目的

五年后换人
五年后换电脑
项目依然能编译

⭐ 一句话总结

不仅保存源码，更要保存能编译源码的环境。

---

🟢 原则四：接受重写是工程生命周期的一部分

⭐ 出现以下情况时考虑重构/重写

• 版本迭代到 v3.x+

• Bug累计数百个

• 团队更替多轮

• 新功能开发成本越来越高

⭐ 不要总问

怎么继续修？

⭐ 而要问

是否应该重构？
是否应该重写？

⭐ 一句话总结

软件不会永生，适时重构和重写是正常工程行为。

---

⭐ 全文总结

嵌入式项目难维护的根本原因：

资源约束
+
调试成本高
+
状态耦合
+
工具链衰变
+
知识流失

应对原则：

记录为什么
+
统一状态管理
+
固化开发环境
+
及时重构

⭐ 最值得记住的一句话

你无法阻止项目老化，但可以让它老化得更慢一些。