JavaScript 注释

JavaScript 注释详解注释是代码中不会被 JavaScript 引擎执行的文本主要用于解释代码逻辑、记录开发思路或临时禁用代码。良好的注释习惯能显著提高代码的可读性和可维护性。JavaScript 支持两种主要类型的注释单行注释和多行注释。1. 单行注释 (Single-line Comments)使用双斜杠//开头。从//开始到该行末尾的所有内容都会被忽略。基本用法// 这是一个单行注释letname张三;// 行尾注释解释变量含义letage18;常见场景解释单行代码// 计算圆的面积constareaMath.PI*radius*radius;临时禁用代码调试常用console.log(正常日志);// console.log(这行代码被暂时禁用了);console.log(继续执行);代码块标记// // 用户认证模块// functionlogin(){...}2. 多行注释 (Multi-line Comments)使用/*开头*/结尾。可以跨越多行也可以用于单行。基本用法/* 这是一个多行注释 可以占据多行 常用于文件头说明或复杂逻辑解释 */letx10;常见场景文件头文档/* * 文件名user.js * 作者张三 * 创建日期2024-01-01 * 描述处理用户相关逻辑 */解释复杂逻辑/* * 算法说明 * 1. 遍历数组 * 2. 过滤出偶数 * 3. 计算总和 */constsumnumbers.filter(nn%20).reduce((acc,n)accn,0);临时注释大块代码/* function oldFunction() { console.log(旧逻辑); // ... 更多旧代码 } */3. JSDoc 注释 (文档注释)JSDoc 是一种特殊的注释格式以/**开头*/结尾。它被广泛用于生成 API 文档并得到 IDE 的智能提示支持。基本语法/** * 计算两个数的和 * param {number} a - 第一个加数 * param {number} b - 第二个加数 * returns {number} 两数之和 * example * const result add(2, 3); // 5 */functionadd(a,b){returnab;}常用标签param {类型} 参数名 - 描述描述函数参数returns {类型} - 描述描述返回值example提供使用示例author作者信息version版本号deprecated标记已废弃的 APIthrows描述可能抛出的异常在 IDE 中的效果在 VS Code 等现代编辑器中将鼠标悬停在函数名上会显示 JSDoc 注释生成的提示框极大提升开发体验。4. 注释的最佳实践✅ 推荐做法解释“为什么”而不是“是什么”// ❌ 不好的注释显而易见i;// i 加 1// ✅ 好的注释解释原因i;// 跳过第一个元素从第二个开始处理保持注释与代码同步代码修改后务必更新相关注释避免误导。使用 JSDoc 描述公共 API对于库函数、模块导出函数务必使用 JSDoc。避免过度注释代码本身应该清晰易懂注释应补充代码无法表达的信息。❌ 避免的做法注释掉大量代码使用版本控制系统如 Git管理代码历史而不是在代码中注释掉旧代码。无意义的注释// 定义变量 xletx10;注释中包含过时信息如果逻辑已改变注释必须同步更新。使用注释隐藏 Bug不要通过注释掉代码来“修复”问题应真正解决问题。5. 特殊注意事项注释中的转义在注释中不需要转义特殊字符但要注意不要意外结束注释/* 这是一个注释 注意不能在这里写 */否则注释会提前结束*/正则表达式中的斜杠在正则表达式中/是分隔符不要与注释混淆// ✅ 正确letregex/\/\//;// 匹配两个斜杠// ❌ 错误会被误认为注释开始letregex// 匹配斜杠模板字符串中的注释模板字符串内部不支持注释语法// ❌ 错误letstr这是模板字符串 // 这不会被识别为注释;// ✅ 正确letstr这是模板字符串${// 这只是一个字符串};6. 注释工具推荐VS Code单行注释Ctrl /(Windows) 或Cmd /(Mac)多行注释选中代码后按Shift Alt A(Windows) 或Shift Option A(Mac)JSDoc 生成工具JSDoc官方工具TypeDocTypeScript 专用ESDoc现代 JavaScript 文档工具7. 示例完整的注释实践/** * 用户认证模块 * module auth * version 1.0.0 * author 开发团队 *//** * 验证用户登录 * param {string} username - 用户名 * param {string} password - 密码 * returns {Promiseboolean} 验证结果 * throws {Error} 当网络请求失败时 * example * const isValid await validateUser(zhangsan, 123456); */asyncfunctionvalidateUser(username,password){// 参数校验if(!username||!password){thrownewError(用户名和密码不能为空);}try{// 发送登录请求constresponseawaitfetch(/api/login,{method:POST,headers:{Content-Type:application/json},body:JSON.stringify({username,password})});// 处理响应if(!response.ok){thrownewError(登录失败);}constdataawaitresponse.json();returndata.success;}catch(error){// 记录错误日志console.error(登录验证出错:,error);throwerror;}}// 临时禁用旧版本代码/* function oldValidate(username, password) { // 旧逻辑... } */良好的注释习惯是专业开发者的标志。记住代码是写给人看的只是恰好能被机器执行。恰当的注释能让你的代码更易读、更易维护。