写代码的时候，顺手加上几句注释，本是为了方便自己和别人看懂。可时间一长，代码改了几轮，注释却原地不动，这时候问题就来了：注释还需要更新吗？答案是肯定的——不更新的注释比没注释更可怕。
注释变“谎言”，调试踩坑少不了
老张是公司前端组的骨干，上周接手了一个老项目做功能迭代。他在一段函数上方看到这样一行注释：
// 该函数只接收用户ID，返回基础信息，不包含权限数据结果他照着这句提示写逻辑，上线后发现页面权限乱套了。查了半天才发现，这个函数半年前已经升级，现在返回的数据里明明包含了角色和权限字段。那句注释早就过时了，可没人动它。
这就是典型的“死注释”问题。它不仅没帮忙，反而误导人，浪费排查时间。
什么时候必须更新注释？
只要代码行为变了，注释就得跟着变。比如你把一个同步函数改成异步，原来的注释写着“立即返回结果”，那就得改成“返回Promise，需等待解析”。再比如接口参数从手机号改成了用户Token，相关的说明也得同步调整。
还有种情况容易被忽略：删除代码时，连带的注释最好也清理掉。别在文件里留一堆孤零零的说明段落，像废弃的路标，让人怀疑是不是漏了什么重要信息。
怎么写注释才不容易过时？
与其指望事后更新，不如一开始写得聪明点。少写“做了什么”，多写“为什么这么做”。比如：
// 避免频繁请求，缓存有效期设为10分钟（服务器定时任务每10分钟刷新一次）这种注释解释的是设计意图，就算将来改成8分钟或用WebSocket推送，只要原因没变，注释依然有效。
相反，如果只写“缓存时间：600秒”，等数值一改，这句就立刻失效。
团队协作中别忽视注释管理
在Code Review时，很多人只盯逻辑和性能，很少有人提“你这注释没更新”。建议把注释准确性也纳入审查清单。合并PR前扫一眼相关注释，顺手改一句，能省下后续好几小时沟通成本。
有些团队用自动化工具检查注释与代码的一致性，比如对API文档生成器做校验。哪怕没有工具，养成“改代码顺手看注释”的习惯，也能避免不少麻烦。
注释不是写完就完事的事。它和代码一样，需要维护。别让它成为项目里的“僵尸内容”，安静地误导下一个读代码的人。