JavaScript注释完全指南
编程小白也能看懂的JavaScript注释知识点汇总
注释就像代码里的便利贴，是写给人类看的笔记，电脑会完全忽略它们。合理使用注释能让你的代码更容易理解和维护！
一、注释的基本类型
1. 单行注释
使用两个斜杠 //，只能写一行内容
// 这是单行注释，只对本行有效
let age = 25; // 在代码后面也可以添加注释
let age = 25; // 在代码后面也可以添加注释
2. 多行注释
使用 /* 开头和 */ 结尾，可以跨越多行
/* 这是多行注释
可以写很多行内容
适用于较长的说明 */
function calculateTotal() {
// 函数内容
}
可以写很多行内容
适用于较长的说明 */
function calculateTotal() {
// 函数内容
}
3. JSDoc注释（专业版）
特殊的注释格式，用于生成文档，以 /** 开头
/**
* 计算两个数字的和
* @param {number} a 第一个数字
* @param {number} b 第二个数字
* @returns {number} 两个数字的和
*/
function add(a, b) {
return a + b;
}
* 计算两个数字的和
* @param {number} a 第一个数字
* @param {number} b 第二个数字
* @returns {number} 两个数字的和
*/
function add(a, b) {
return a + b;
}
💡 小贴士
单行注释适合简短的说明，多行注释适合详细解释，JSDoc注释适合正式的函数文档。
二、注释有什么用？
📝 解释代码意图
说明代码的目的，而不仅仅是代码在做什么
// 检查用户是否满18岁（好的注释）
if (age >= 18) { … }
// 如果年龄大于等于18（差的注释 – 太明显）
if (age >= 18) { … }
if (age >= 18) { … }
// 如果年龄大于等于18（差的注释 – 太明显）
if (age >= 18) { … }
⚠️ 标记待办事项
标记需要后续处理的地方
// TODO: 需要添加错误处理
// FIXME: 这里的计算可能有精度问题
// FIXME: 这里的计算可能有精度问题
🚧 临时禁用代码
调试时暂时禁用某些代码
console.log(‘调试信息’);
// console.log(‘这个暂时不需要’);
// console.log(‘这个暂时不需要’);
❗ 重要提示
注释不能替代清晰的代码！好的代码应该像故事一样自解释，注释只是补充说明。
三、注释的最佳实践
1. 保持注释更新
过时的注释比没有注释更糟糕！修改代码时要同步更新注释。
2. 避免明显注释
// 将x设为10（不好的注释）
let x = 10;
let x = 10;
3. 使用简洁的语言
使用清晰、简洁的语言，避免复杂术语（除非你的团队都懂）
4. 解释”为什么”而不是”是什么”
// 使用位运算提高性能（解释为什么）
const isPowerOfTwo = n => (n & (n – 1)) === 0;
const isPowerOfTwo = n => (n & (n – 1)) === 0;
5. 复杂算法要注释
对于复杂的逻辑，注释是救命稻草
// 使用快速排序算法实现高效排序
// 分治策略：选择基准，分割数组，递归排序
function quickSort(arr) { … }
// 分治策略：选择基准，分割数组，递归排序
function quickSort(arr) { … }
💡 注释的艺术
好的注释就像给代码添加了字幕，让读者更容易理解剧情！
四、常见错误与避免方法
❌ 注释过多
每行都加注释会让代码难以阅读，只在必要处添加。
❌ 情绪化注释
避免在注释中发泄情绪，保持专业。
// 这个愚蠢的补丁，都是因为PM的愚蠢需求
❌ 大段注释不换行
长段落难以阅读，适当换行分段。
🎯 注释的核心原则
好的注释应该像一位优秀的导游：
1. 在复杂路段提供指引
2. 解释背后的历史故事
3. 不干扰游客欣赏风景
4. 及时更新路线信息