写代码时顺手打上几个注释，本是为了让别人或几个月后的自己能看懂逻辑。可有时候，一个不小心，注释反而成了bug的温床。比如你删了一段代码，但忘了清理对应的注释，后来人照着注释理解，结果越看越懵；或者更惨的，注释写错了，误导整个调试方向。
注释写错有多常见？
别以为这只是小问题。我朋友老张在公司维护一个老项目，里面有段处理时间戳的函数，注释写着“输入为毫秒级时间”，结果实际传进来的是秒级。他按注释改逻辑，折腾一整天才发现是注释写反了。这种“好心办坏事”的情况，在团队协作里太常见了。
怎么避免被注释带偏？
最直接的办法就是：别全信注释。看到可疑的地方，动手验证一下。比如遇到下面这种情况：
// 返回用户年龄（单位：月）
function getUserAge(userId) {
return Math.floor((Date.now() - user.birthTime) / (1000 * 60 * 60 * 24 * 30));
}看起来没问题吧？但如果你真这么用，可能会发现结果对不上。其实这个函数算的是整月数没错，但万一需求是要精确到年再换算呢？注释没说清，就容易出事。
推荐两个实用工具
与其靠人自觉，不如让工具帮你盯住注释质量。第一个是 ESLint 的 valid-jsdoc 规则，能检查 JSDoc 注释是否和函数签名匹配。一旦参数名写错、类型不符，立马报错。
另一个是 DocDog，它可以定期扫描项目里的注释，找出长时间未更新、与代码行为不一致的内容。比如某函数已经重构过三次，但注释还停留在第一版逻辑，它就会标出来提醒你。
写注释也有技巧
与其事后补救，不如一开始就把注释写明白。记住三点：不说废话，不重复代码，讲清楚“为什么”而不是“做什么”。比如：
// 错误示范：重复代码逻辑
// 如果用户未登录，则跳转到登录页
if (!user) {
redirect('/login');
}
// 正确示范：说明背后原因
// 必须强制登录，因为后续接口需要身份凭证
if (!user) {
redirect('/login');
}这样一写，别人就知道这不是随便加的判断，而是业务硬性要求。
团队协作更要规范起来
建议在代码评审时多问一句：“这句注释现在还准确吗？” 尤其是修改旧功能时，很多人只改代码不改注释。可以在 Git 提交检查中加入注释一致性扫描，把这类低级错误挡在上线前。
注释本该是帮手，别让它变成陷阱。改代码的时候，顺手看看旁边的注释是不是也该动一动，省得给别人挖坑，也省得将来自己爬不出来。