注释中避免写什么：程序员写注释的常见错误

写代码时加注释，本是为了让别人或未来的自己更快看懂。但有时候，注释没写对，反而成了累赘，甚至误导人。尤其在团队协作中，一句多余的注释可能让人花半小时排查一个根本不存在的问题。

比如这段代码：

// 给 num 加 1
num++;

这种注释纯属多余。代码本身已经足够清晰，再写一遍等于在文档里抄代码。就像在冰箱上贴纸条写着“牛奶在这里”，谁不知道牛奶在冰箱里？

代码改了，注释没改，是最危险的情况。例如：

// 返回用户年龄（单位：月）
return user.getAgeInYears();

函数明明返回的是年份，注释却说是月份。新来的同事信了注释，计算逻辑全错，查半天才发现是注释撒了谎。比没注释更糟的是骗人的注释。

像“// 别动这个，我也不知道为啥但能跑”或者“// 这段很烂，但老板催得紧”这类话，虽然真实，但不适合留在代码里。项目是长期维护的，情绪化注释只会让后来者困惑，甚至影响团队氛围。真有问题，该重构就重构，而不是在注释里抱怨。

有些人喜欢用注释拆解每一步：

// 先检查用户是否登录
if (user.isLoggedIn()) {
    // 如果登录了，获取数据
    fetchData();
}

这种逐行翻译式的注释，看着像是教学示例，但在实际项目中只会拉长文件、干扰阅读。真正需要注释的是“为什么这么做”，而不是“做了什么”。

与其写注释解释变量用途，不如直接起个好名字。比如：

// 过期时间，单位秒
int t = 3600;

不如直接写成：

int expirySeconds = 3600;

名字清楚了，注释自然就不需要了。好代码是自解释的，注释只是补充。

有人调试时把代码注掉，还留着说“备用”：

// oldService.call(data); // 旧接口已弃用
// if (flag) { doOldLogic(); }

时间一长，没人知道这些是历史遗迹还是临时屏蔽。版本管理工具才是干这活的，注释不是代码坟场。该删就删，要用再从 Git 拿。

注释不是越多越好，而是越准越好。它不该重复代码，不该滞后更新，更不该成为情绪垃圾桶。把注释当成对话——你是在跟未来的读者认真解释关键决策，而不是随手记下当时的心情日记。

注释中避免写什么：程序员常踩的坑