JavaScript 注释实用指南：高效开发的注释技巧与规范

在日常 JavaScript 开发中，“注释”看似小事，实则对开发效率、协作质量有深远影响。本篇文章将从快捷键实用技巧、使用场景、规范建议等方面，系统梳理 JavaScript 中的注释使用方式。

一、注释类型与快捷键速查

类型语法快捷键（VS Code）快捷键（WebStorm）用途单行注释//Ctrl + /Cmd + / (Mac) / Ctrl + /注释当前行或多行多行注释/* ... */Ctrl + shift + aCtrl + shift + / 屏蔽大段逻辑、写说明JSDoc 注释/** ... */输入 /** 后回车输入 /** 后回车为函数/类添加结构化文档

💡 快捷键适用于选中多行时批量注释/取消注释。

📌 以上单行注释、多行注释快捷键同样适用于 HTML 、CSS 中的 注释。

二、实用场景分类：什么时候用什么注释？

1. ✅ 单行注释 //

适用于：

说明某行代码的 目的 / 特殊性临时代码屏蔽结构化分隔（配合标记符号）

// 初始化用户信息

let user = getUserInfo();

// === 处理权限逻辑 ===

2. ✅ 多行注释 /* ... */

适用于：

屏蔽一段多行代码写一段较长的文字说明（如模块说明）暂时代码降级处理

/*

兼容 IE 的兜底处理（旧版已废弃）

try {

oldBrowserFallback();

} catch (e) { ... }

*/

⚠️ 多行注释不能嵌套，如果要注释一段包含注释的代码，推荐使用 //。

3. ✅ JSDoc 注释 /** ... */

适用于：

为函数、类、对象写结构化说明给团队或自己未来的维护者留下清晰“接口文档”

/**

* 计算商品折扣价

* @param {number} price - 原价

* @param {number} rate - 折扣率（0-1）

* @returns {number} - 折后价格

*/

function getDiscountPrice(price, rate) {

return price * rate;

}

常见 JSDoc 字段解释 ：

标签名含义用法示例说明@param参数说明@param {string} name 用户名标注参数类型、名字、说明@returns / @return返回值说明@returns {boolean} 是否成功标注返回类型和说明@throws / @exception异常说明@throws {Error} 参数非法函数内部可能抛出的异常@deprecated标记过时@deprecated 不再使用，请用 xxx 方法说明该函数不建议再使用@example使用示例@example getName('Tom') // => 'Tom'展示如何调用@typedef自定义类型@typedef {Object} User用于定义复杂对象结构@property对象属性说明（配合 typedef）@property {string} name描述对象内部结构@type标注变量类型@type {number}给变量添加类型说明现代 IDE（VS Code / WebStorm）会自动识别 JSDoc，支持类型提示和跳转。

三、注释风格与团队规范建议

为了让注释更具可读性与一致性，推荐遵循以下规范：

1. ✏️ 注释写“为什么”，而不是“做了什么”

// ❌ 差：说明了明显的操作

// 增加1

count++;

// ✅ 好：说明意图

// 用户点击后累加一次行为计数

count++;

2. 📏 保持一致的风格与格式

统一注释分隔样式，有助于代码结构更清晰。

// === 请求配置区域 ===

// --- 工具函数 ---

// *** 表单处理 ***

3. 📌 标记 TODO / FIXME / HACK

使用标准标记能让团队快速定位问题代码：

// TODO: 优化这段异步逻辑

// FIXME: 修复偶发性为空的情况

// HACK: 为了兼容某旧接口的临时处理

四、注释的实用技巧和注意事项

✅ 实用技巧：

配合插件使用（如 VS Code 的 Better Comments）注释中的关键字可统一标色：[!], [NOTE], [WARN]编辑器设置高亮 TODO / FIXME 提醒

❌ 常见误区：

注释写得太冗长或废话（如：// 声明一个变量）注释没及时更新，反而误导把注释当“备份代码区”，造成污染

五、开发实战中的注释策略建议

场景建议注释策略复杂逻辑判断写明“边界条件”的意图正则表达式写清楚规则作用接口调用写清请求结构、响应样例（推荐使用 JSDoc）公共工具函数必须添加用途说明 + 参数说明临时逻辑或兼容处理用 TODO / FIXME 明确说明

结语：注释是团队协作的桥梁，不是负担

代码是给人看的，顺便能跑；注释是给未来的你看的，千万别吝啬。

如果你想写出更专业、更可维护的 JavaScript 代码，不妨从一套好的注释习惯开始。

🧰 附赠：常用注释标记模板

// ================= 模块说明 =================

// 功能：用户登录模块

// 依赖：axios, store, utils

// 作者：张三，2025-06-03

// ==========================================

// TODO: 登录时加入短信验证码验证

// FIXME: 处理 token 过期自动刷新问题

如果你觉得这篇实用指南对你有帮助，欢迎收藏、评论交流你的注释技巧！