异常教程

JavaScript 注释（长文解析）

更新时间:

💡一则或许对你有用的小广告

欢迎加入小哈的星球 ，你将获得：专属的项目实战 / 1v1 提问 / Java 学习路线 / 学习打卡 / 每月赠书 / 社群讨论

截止目前， 星球 内专栏累计输出 90w+ 字，讲解图 3441+ 张，还在持续爆肝中.. 后续还会上新更多项目，目标是将 Java 领域典型的项目都整一波，如秒杀系统, 在线商城, IM 即时通讯，权限管理，Spring Cloud Alibaba 微服务等等，已有 3100+ 小伙伴加入学习 ，欢迎点击围观

前言

在编程的世界中，代码是开发者与计算机沟通的“语言”，而 JavaScript 注释 则是开发者之间传递“暗号”的桥梁。无论你是刚接触编程的新手，还是有一定经验的开发者，理解并善用注释，都能让你的代码更清晰、更易维护。本文将从基础概念到实战技巧，逐步解析 JavaScript 注释 的核心要点，并通过具体案例帮助你掌握如何让注释真正成为代码的“说明书”。

一、JavaScript 注释的类型与语法

1.1 单行注释：代码中的“旁白”

单行注释是最基础的注释形式，使用 // 符号后紧跟注释内容。它如同代码行旁的“旁白”，即时解释当前行的逻辑。

示例代码：

// 计算两个数的和  
let sum = 5 + 3; // 这里将得到 8

比喻说明：
想象你正在阅读一本小说，作者在页边写下“此处是关键转折点”——单行注释的作用类似，它帮助读者快速抓住代码的“剧情走向”。

1.2 多行注释：包裹代码的“透明屏障”

多行注释使用 /* */ 包裹，适用于需要解释多行代码或临时屏蔽代码块的场景。

示例代码：

/*  
这是多行注释的示例，  
可以跨越多行，  
常用于解释复杂逻辑。  
*/  

// 临时屏蔽代码  
// function sayHello() { /* ... */ }

注意事项：
在 JavaScript 中，多行注释不能嵌套。例如：

/* 这是错误的写法  
/* 嵌套注释会引发语法错误 */  
*/

1.3 文档注释：代码的“官方指南”

文档注释以 /** */ 开头，常用于生成 API 文档或标注函数、类的详细信息。它配合工具（如 JSDoc）可自动生成结构化文档。

示例代码：

/**  
 * 计算两个数的和  
 * @param {number} a - 第一个加数  
 * @param {number} b - 第二个加数  
 * @returns {number} 两数之和  
 */  
function add(a, b) {  
  return a + b;  
}

工具支持：
通过 JSDoc 工具，上述代码可生成类似以下文档：

FUNCTION: add(a, b)  
PARAMS:  
  a (number): 第一个加数  
  b (number): 第二个加数  
RETURN:  
  number: 两数之和

二、注释的最佳实践与常见误区

2.1 注释的“黄金法则”

  • 解释“为什么”，而非“是什么”：

    // 正确：解释意图  
// 因为用户需要实时反馈，因此设置 100ms 的延迟  
setTimeout(updateUI, 100);  

// 错误：重复代码逻辑  
// 设置 100ms 的延迟（代码已经明确显示）  
setTimeout(updateUI, 100);

  • 函数/方法必须注释：
    对于复杂函数，务必通过文档注释说明输入、输出及行为。

  • TODO 注释：未来的“待办清单”：

    // TODO: 需要优化此循环的性能  
for (let i = 0; i < largeArray.length; i++) {  
  // ...  
}

2.2 需避免的常见误区

误区类型具体表现解决方案
过度注释对显而易见的代码添加冗余注释（如 let count = 0; // 初始化计数器）删除冗余注释，专注于复杂逻辑的解释
注释与代码不一致代码逻辑修改后，未同步更新注释（如 // 此函数返回用户 ID（实际返回的是用户名））建立代码审查流程，确保注释与代码同步更新
滥用 TODO 注释积累大量未处理的 TODO 注释，形成“技术债务”定期清理 TODO 列表，或通过任务管理工具跟踪

三、进阶技巧：让注释更高效

3.1 结合工具自动化注释管理

  • ESLint 规则：通过配置 ESLint 的 no-unused-vars 或 valid-jsdoc 规则，强制开发者为函数添加注释。
  • 代码模板：在编辑器中设置代码片段，自动生成文档注释模板： 
    /**  
 * ${1:描述}  
 * @param {${2:type}} ${3:name} - ${4:说明}  
 * @returns {${5:type}} ${6:返回值说明}  
 */

3.2 用注释辅助调试

在调试时，可以通过注释快速隔离问题代码：

// 单行注释临时禁用某行  
// console.log(error);  

/*  
// 多行注释包裹代码块  
if (condition) {  
  // ...  
}  
*/

四、实战案例：注释在真实项目中的应用

4.1 案例 1：解释复杂算法

/**  
 * 快速排序算法实现  
 * @param {Array<number>} arr - 待排序数组  
 * @returns {Array<number>} 排序后的数组  
 */  
function quickSort(arr) {  
  if (arr.length <= 1) return arr;  
  const pivot = arr[Math.floor(arr.length / 2)];  
  const left = []; // 小于基准值的元素  
  const right = []; // 大于基准值的元素  

  for (let num of arr) {  
    if (num < pivot) left.push(num);  
    else if (num > pivot) right.push(num);  
  }  

  return [...quickSort(left), pivot, ...quickSort(right)]; // 递归合并  
}

4.2 案例 2：标注第三方 API 的使用

/**  
 * 调用天气 API 获取当前城市温度  
 * @param {string} city - 城市名称  
 * @returns {Promise<number>} 温度值（摄氏度）  
 */  
async function getTemperature(city) {  
  const response = await fetch(`https://api.weather.com/${city}`);  
  const data = await response.json();  
  return data.temperature; // 假设 API 返回的字段为 temperature  
}

结论

JavaScript 注释不仅是代码的“注脚”，更是开发者协作与长期维护的基石。通过合理使用单行、多行和文档注释，并遵循最佳实践，你能让代码更易读、更健壮。记住：注释的终极目标是让他人（或未来的自己）无需猜测代码的意图。

无论是通过工具自动化管理，还是在复杂算法中添加“路标”，注释始终是提升代码质量的关键一环。现在就开始优化你的注释习惯吧，让每一行代码都成为可信赖的“说明书”！

最新发布

查看更多文章