JavaScript 注释别乱写：一套让队友感激涕零的规范指南

代码写的时候顺手，三个月后自己都能被绕晕。相信不少前端开发者都经历过这种时刻：接手旧项目，看到满屏没有逻辑关联的变量名和魔法数字，第一反应不是“这功能挺强”，而是“谁干的”。其实，问题往往不出在逻辑上，而在注释的缺失或混乱。

很多人对注释有误解，觉得它是给机器看的提示，或者为了应付检查写的废话。注释的核心永远是“为什么”，而不是“是什么”。 代码本身已经清晰地表达了它在做什么，不需要你再用文字复述一遍。比如看到 i++，旁边的注释如果是 // i 加 1，那纯属占用屏幕空间。真正有价值的注释，是解释这段看似奇怪的代码背后的业务原因。举个例子，如果代码里有 const MAX_LIMIT = 134;，单纯的变量命名看不出意义。加上注释 // 支付网关单笔交易限额上限（元），阅读者瞬间就能理解这个数字的来源，修改时也会更加谨慎。

对于公共函数或对外暴露的方法，JSDoc 格式几乎是必选项。团队协作中，接口契约就是信任的基础。哪怕是个内部私有函数，只要涉及到复杂参数，写上 @param 和 @returns 能省去大量口头沟通成本。特别是在处理异步流程时，明确 Promise 的类型和 reject 的理由，能有效避免后续接入方踩坑。不要觉得麻烦，定义好参数类型，有时候比写一堆 console.log 调试来得更直接。

另一种常见的情况是遗留代码的清理。写代码过程中遇到未实现的模块，用 // TODO: 或 // FIXME: 标记很正常，但别让它们成为仓库里的僵尸。有些注释写着“待优化性能”，结果三年过去了还是原封不动。这类临时标记必须有归宿，如果问题解决了，记得把注释删掉；如果需要长期跟踪，最好关联到具体的任务 ID。留着无用的 TODO 只会让后来者误以为这里还有 Bug，进而花费时间去排查不存在的问题。

依赖人的自觉性去维护注释规范，通常难以持久。比起人治，工具链的约束更靠谱。 在项目里配置 ESLint 规则，比如引入 eslint-plugin-jsdoc，强制要求公共函数必须包含 JSDoc，或者检测是否存在未使用的注释块。当编辑器直接标红报错时，大家自然就会养成习惯。同时，利用 Git 提交记录作为辅助文档，复杂的逻辑变更配合 Commit Message，比代码里的长篇大论更清晰。

好的注释就像路标，不是为了证明你走了多远，而是为了让后来的人少走弯路。它体现的不是技术高度，而是对合作者的尊重。从今天开始，少写点废话，多留点真意，你的代码库会变成团队的财富，而不是负担。