明确函数职责、标记待优化项、解释反直觉逻辑、添加模块级注解可提升代码可维护性。使用 JSDoc 注解函数参数与返回值，配合 TODO/FIXME/HACK 标签标识技术债务，说明特殊逻辑避免误改，文件头注解描述模块设计意图，有助于团队协作与长期迭代。
JavaScript 注解（注释）不是可执行代码，但写得好能极大提升项目的可维护性。尤其在团队协作或长期迭代中，清晰的注解能让开发者快速理解函数意图、逻辑边界和潜在风险。以下是几种实用技巧，帮助你通过注解有效优化代码后期维护。
明确函数职责与参数说明
每个函数都应有简明扼要的注解，说明其作用、参数类型、返回值及可能的副作用。
/*** 计算用户折扣后的价格
* @param {number} price - 原价，必须为正数
* @param {string} level - 用户等级：'basic', 'premium', 'vip'
* @returns {number} 折后价格，保留两位小数
* @throws 如果 level 不合法则抛出错误
*/
function calculateDiscount(price, level) { ... }
这类结构化注解配合工具（如 JSDoc）还能生成文档，便于新人快速上手。
标记待优化或临时方案
开发过程中难免写出临时逻辑或已知缺陷，使用标准化标签让后续维护者一眼识别。
- // TODO: 支持多币种计算 —— 表示功能待完善
- // FIXME: 修复 Safari 下日期解析异常 —— 标记已知问题
- // HACK: 绕过第三方库的 bug —— 说明非标准做法
这些标签可被 IDE 或静态检查工具识别，便于追踪技术债务。
解释“反直觉”逻辑
有些代码看似冗余或复杂，实则解决特定边界问题。不加注解容易被误删。
if (value === 0 || value) {
// 允许 0 作为有效值，避免被 falsy 判断过滤
return format(value);
}
类似这种判断，加上一行说明就能避免他人重构时引入 bug。
模块级注解说明设计意图
在文件顶部添加模块说明，描述该文件的职责、依赖关系和使用方式。
/*** 用户状态管理模块
* 负责登录态维持、token 刷新及登出清理
* 依赖 authApi 和 localStorage
* 使用前需调用 initAuth() 初始化
*/
这比只看函数名更能帮助开发者理解整体结构。
基本上就这些。好的注解不是越多越好，而是精准传达“为什么这么写”。保持简洁、一致、结构化，才能真正提升后期维护效率。
