重构代码时注释怎么写才真正有用

在家折腾智能家居系统的时候，免不了要翻自己半年前写的脚本。打开一看，一堆函数堆在那儿，名字叫 doSomething、handleData，再往下看，连自己都懵了：这玩意儿到底干啥的？这时候才意识到，光写代码不行，得让别人（包括未来的自己）能看懂。

别写“废话式”注释

很多人写注释图省事，比如：

// 设置变量 a 为 1
int a = 1;

// 调用发送函数
send(message);

这种注释跟没写差不多。代码本身已经说了“做了什么”，但没说“为什么这么做”。真正有用的注释，是补全那些代码无法表达的上下文。

重点写清楚“为什么”，而不是“做什么”

比如你在写一个家庭网络状态检测脚本时，发现路由器在凌晨两点会短暂掉线，于是加了个重试机制：

// 路由器固件存在 bug，凌晨 2:00-2:05 会断开 PPPoE 连接
// 临时方案：失败后最多重试 3 次，间隔 20 秒
for (int i = 0; i < 3; i++) {
    if (checkNetwork()) break;
    sleep(20);
}

这段注释提供了关键背景：问题时间、原因、解决方案的边界条件。下次你或家人接手维护，一眼就知道这不是随便写的逻辑。

重构时，注释也要跟着更新

很多人重构完代码，函数功能变了，名字改了，但注释还留在原地，写着旧逻辑。这比不写更危险，因为它会误导人。

比如原来注释写的是“从本地传感器读取温度”，结果你后来改成从远程 API 拉数据，但忘了改注释。下回排查延迟问题时，别人可能白白浪费时间去查本地硬件。

所以每次调整逻辑，顺手扫一眼旁边的注释，确认它还说得通。

复杂逻辑用“段落式”注释讲清楚流程

家庭自动化脚本里常有状态机，比如“当门磁触发 + 室内无人 + 时间在晚上，才发报警”。这种逻辑适合在函数开头写一段说明：

/*
 * 入侵检测主逻辑
 * 触发条件：
 * - 门/窗磁传感器激活
 * - 家庭成员均标记为“外出”（通过手机定位判断）
 * - 当前时间为 22:00 至 06:00 之间
 * 满足以上三点，推送紧急通知并启动摄像头录像
 */
void checkIntrusion() { ... }

这样一读就明白整个判断链条，不用一行行抠代码去猜。

别怕用中文写注释

尤其是家里其他人也可能接触这些脚本时。你爸想看看为啥半夜空调自动关了，结果打开代码全是英文注释，根本看不懂。用大白话写清楚：

// 老人睡觉怕冷，晚上 11 点后把空调调高 1℃
if (hour == 23) setTemp(targetTemp + 1);

既清晰又贴心，技术不是用来炫的，是为生活服务的。