文档/教程前端【免费下载链接】en.javascript.infoModern JavaScript Tutorial项目地址https://gitcode.com/gh_mirrors/en/en.javascript.info点击查看免费下载本篇指南源自 Modern JavaScript Tutorial 项目「代码质量」章节中的《Comments》一文见 1-js/03-code-quality/03-comments/article.md系统讲解 JavaScript 代码注释的正确打开方式哪些注释是新手常犯的错误、哪些注释值得保留、以及如何通过抽出函数自描述代码等重构手法让代码本身替你说话。读完你将掌握一套可直接套用的注释取舍标准并了解 JSDoc 等自动化文档工具的使用方法让注释真正服务于代码维护而不是成为噪音。先打好语法地基注释的两种基本形式在讨论该不该写注释之前先明确 JavaScript 注释的两种语法形式它们早在「代码结构」章节就有过完整介绍见 1-js/02-first-steps/02-structure/article.md#L93-L153单行注释以两个正斜杠//开头行尾结束。可以独占一行也可以跟在一条语句之后// This comment occupies a line of its own alert(Hello); alert(World); // This comment follows the statement多行注释以/*开头、*/结尾可以跨越多行/* An example with two messages. This is a multiline comment. */ alert(Hello); alert(World);关于注释语法有两点容易被新手忽略的事实注释内容完全被引擎忽略。把代码放进/* ... */中就不会执行因此多行注释常被用来临时注释掉一段代码以禁用功能/* Commenting out the code alert(Hello); */ alert(World);嵌套注释不受支持。/*...*/内部不能再出现另一层/*...*/否则代码会直接报错——这一点与 CSS 等语言不同务必留意。注释不影响生产环境性能。虽然注释会增大代码体积但发布到生产服务器前通常会有压缩minify工具自动剥离注释因此大胆写注释不会有任何负面开销。关于快捷键在大多数编辑器中Ctrl/Mac 为Cmd/可注释/取消注释单行选中代码块后按下CtrlShift/Mac 为CmdOption/可快速生成多行注释。坏注释解释代码在做什么编程新手最常见的误区就是用注释去描述代码的执行过程——这段代码做了什么// This code will do this thing (...) and that thing (...) // ...and who knows what else... very; complex; code;在高质量代码中这类解释性注释应当被压缩到最少。代码本身应当足够清晰让人无需借助注释就能读懂。业内有一条非常经典的原则如果一段代码晦涩到必须靠注释才能看懂那正确的做法是重写它而不是注释它。也就是说解释性注释的存在往往不是注释的问题而是代码设计的问题。与其用注释为糟糕的代码辩解不如动手改善代码本身。下面给出教程中提出的两条具体重构配方。配方一抽出函数factor out functions考虑下面的showPrimes它的内层循环里用一段注释标出检查 i 是否为素数function showPrimes(n) { nextPrime: for (let i 2; i n; i) { // check if i is a prime number for (let j 2; j i; j) { if (i % j 0) continue nextPrime; } alert(i); } }更好的写法是把素数判断抽成独立的isPrime函数让调用处的逻辑一目了然function showPrimes(n) { for (let i 2; i n; i) { if (!isPrime(i)) continue; alert(i); } } function isPrime(n) { for (let i 2; i n; i) { if (n % i 0) return false; } return true; }重构之后注释消失了但代码反而更容易理解——函数本身就变成了注释。这类代码被称为自描述代码self-descriptive从函数名就能读出意图无需逐行追踪实现细节。配方二把长代码片段改写为函数create functions再看一个更长的例子一段用注释分块的流程清单// here we add whiskey for(let i 0; i 10; i) { let drop getWhiskey(); smell(drop); add(drop, glass); } // here we add juice for(let t 0; t 3; t) { let tomato getTomato(); examine(tomato); let juice press(tomato); add(juice, glass); } // ...每块代码都需要一条这里是干什么的注释恰恰说明代码本身缺少可读的结构。将其重构为语义清晰的函数后主流程变成了一行行的自白addWhiskey(glass); addJuice(glass); function addWhiskey(container) { for(let i 0; i 10; i) { let drop getWhiskey(); //... } } function addJuice(container) { for(let t 0; t 3; t) { let tomato getTomato(); //... } }同样的道理函数名自己说明了一切不再需要注释。而且拆分后代码结构更好——每个函数做什么、接收什么参数、返回什么结果都清晰可辨。无法完全避免解释性注释的例外现实中我们不可能完全消灭解释性注释总存在复杂的算法也总有为优化而生的聪明技巧tweaks它们天然难以一眼读懂。但总的原则不变——尽可能让代码简单、自描述把注释留给真正需要它的地方。好注释真正值得写的内容既然解释性注释通常是坏的那么哪些注释是有价值的教程给出四类好注释。1. 描述整体架构注释应该提供代码的上帝视角组件的高层概览、它们之间如何交互、各种场景下的控制流是怎样的。这类架构级注释帮助后人快速建立全局认知。教程还特别提到UMLUnified Modeling Language统一建模语言——一种专门用于绘制高层架构图、解释代码结构的语言值得花时间学习。2. 文档化函数的参数与用法用专门的 JSDoc 语法为函数编写文档说明用法、参数、返回值。典型示例/** * Returns x raised to the n-th power. * * param {number} x The number to raise. * param {number} n The power, must be a natural number. * return {number} x raised to the n-th power. */ function pow(x, n) { ... }这类注释让你不必翻看函数实现就能理解它的用途并正确调用。JSDoc 的价值还体现在工具链上许多编辑器如 JetBrains 的 WebStorm能解析 JSDoc在写代码时提供自动补全autocomplete和自动代码检查有专门的工具如 JSDoc 3可以读取 JSDoc 注释并自动生成 HTML 格式的文档。这意味着注释不只是一段说明文字更是可编译的文档源材料。补充在教程「代码质量」章节的定位中注释与测试、编码风格共同构成了代码可维护性的三块基石。如果说 JSDoc 是函数级的文档那么行为驱动开发BDD中的 spec 则是行为级的文档——详见 1-js/03-code-quality/05-testing-mocha/article.md#L23-L64测试tests、文档documentation和示例examples三位一体很多代码该怎么用的问题用测试表达往往比用注释更可靠、更不易失真。3. 解释为什么用这种方式解决任务已经写出来的内容重要没有写出来的内容可能更重要。代码本身回答不了为什么为什么这个任务偏偏要这样解决当存在多种解法时为什么选这一种尤其是当它不是最直观的那一种时教程给出了一段非常典型的场景推演你或同事隔了一段时间打开自己写的代码觉得它不够优雅——当时的我多么愚蠢现在的我聪明多了——于是用更显然、更正确的方案重写。结果写着写着发现更显然的方案其实有缺陷你甚至隐约记得原因因为很久以前就试过这条路。最终你回退到正确的版本但时间已经浪费掉了。解释为什么的注释非常重要它能帮助后人沿着正确的方向继续开发避免重复踩坑、重复试错。4. 标注代码中的微妙特性及其使用位置如果代码中有任何**微妙subtle且反直觉counter-intuitive**的地方绝对值得加注释。这类注释提醒读者这里有个坑防止后来者在不理解设计意图的情况下顺手修复而引入回归。与教程其他章节的呼应注释在代码质量体系中的位置注释不是孤立的话题它和教程「代码质量」章节的其他主题紧密咬合编码风格Coding Style自描述代码的前提是良好的命名、合理的缩进和克制的嵌套层级。教程在 1-js/03-code-quality/02-coding-style/article.md#L158-L224 中专门演示了如何用continue、提前return等手段减少嵌套层级——代码结构越平坦需要注释打圆场的地方就越少。忍者代码Ninja Code04-ninja-code章节以反讽口吻总结了所有毁掉可读性的技巧——单字母变量、极端缩写、过度抽象的命名、把代码压到最短见 1-js/03-code-quality/04-ninja-code/article.md。那些需要注释才能解释的复杂代码往往正是这些反模式积累的结果。读者不妨把本篇文章与忍者代码对照阅读前者告诉你注释该怎么写后者告诉你什么代码会逼着人写注释。自动化测试Mocha/BDD如前面所述函数的使用说明完全可以用可执行的测试来表达测试即文档详见 1-js/03-code-quality/05-testing-mocha/article.md。总结注释取舍清单一位优秀开发者的重要标志恰恰体现在注释上——包括注释的存在与缺席。好的注释让你能长期维护代码、隔一段时间回来仍能快速上手、并更有效地使用它。应该注释的内容整体架构、高层视角函数的用法参数、返回值重要的解法尤其是当它并非一眼可见时代码中微妙、反直觉的细节及其使用位置。应该避免的注释描述代码如何工作和代码做了什么的解释性注释只有在无法把代码写得足够简单、自描述时才允许出现这类注释。善用自动化文档工具注释还可以被 JSDoc 这类自动文档工具读取用于生成 HTML 或其他格式的文档——把注释从给人看的话升级为可编译的文档资产。最后记住这句话好的代码自带注释坏的代码才需要注释来辩护。当你想写这段代码在做什么的时候先想想——它能不能被重构得更自描述赞分享文档/教程前端【免费下载链接】en.javascript.infoModern JavaScript Tutorial项目地址https://gitcode.com/gh_mirrors/en/en.javascript.info点击查看免费下载相关推荐NSwag代码生成代码模板注释模板内注释最佳实践NSwag代码生成代码模板注释模板内注释最佳实践 NSwag是一个强大的OpenAPI/Swagger代码生成工具能够自动生成客户端代码和API文档。在NS开发工具代码生成API设计3分钟掌握Headlamp让Kubernetes资源监控变得如此简单3分钟掌握Headlamp让Kubernetes资源监控变得如此简单 你是否曾经面对复杂的Kubernetes集群感到手足无措资源使用情况不明、性能瓶颈难寻云原生开发工具如何快速上手FinMem面向AI交易新手的完整入门指南如何快速上手FinMem面向AI交易新手的完整入门指南 FinMem是一款基于大型语言模型LLM的高性能交易代理框架它融合了分层记忆和角色设计能帮助A上一篇实战指南如何高效集成静态二进制工具到你的Node.js项目下一篇原神模型导入神器GIMI3分钟让你成为游戏角色造型师创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Modern JavaScript Tutorial 代码注释最佳实践：把“解释性注释“变成“自描述代码“
文档/教程前端【免费下载链接】en.javascript.infoModern JavaScript Tutorial项目地址https://gitcode.com/gh_mirrors/en/en.javascript.info点击查看免费下载本篇指南源自 Modern JavaScript Tutorial 项目「代码质量」章节中的《Comments》一文见 1-js/03-code-quality/03-comments/article.md系统讲解 JavaScript 代码注释的正确打开方式哪些注释是新手常犯的错误、哪些注释值得保留、以及如何通过抽出函数自描述代码等重构手法让代码本身替你说话。读完你将掌握一套可直接套用的注释取舍标准并了解 JSDoc 等自动化文档工具的使用方法让注释真正服务于代码维护而不是成为噪音。先打好语法地基注释的两种基本形式在讨论该不该写注释之前先明确 JavaScript 注释的两种语法形式它们早在「代码结构」章节就有过完整介绍见 1-js/02-first-steps/02-structure/article.md#L93-L153单行注释以两个正斜杠//开头行尾结束。可以独占一行也可以跟在一条语句之后// This comment occupies a line of its own alert(Hello); alert(World); // This comment follows the statement多行注释以/*开头、*/结尾可以跨越多行/* An example with two messages. This is a multiline comment. */ alert(Hello); alert(World);关于注释语法有两点容易被新手忽略的事实注释内容完全被引擎忽略。把代码放进/* ... */中就不会执行因此多行注释常被用来临时注释掉一段代码以禁用功能/* Commenting out the code alert(Hello); */ alert(World);嵌套注释不受支持。/*...*/内部不能再出现另一层/*...*/否则代码会直接报错——这一点与 CSS 等语言不同务必留意。注释不影响生产环境性能。虽然注释会增大代码体积但发布到生产服务器前通常会有压缩minify工具自动剥离注释因此大胆写注释不会有任何负面开销。关于快捷键在大多数编辑器中Ctrl/Mac 为Cmd/可注释/取消注释单行选中代码块后按下CtrlShift/Mac 为CmdOption/可快速生成多行注释。坏注释解释代码在做什么编程新手最常见的误区就是用注释去描述代码的执行过程——这段代码做了什么// This code will do this thing (...) and that thing (...) // ...and who knows what else... very; complex; code;在高质量代码中这类解释性注释应当被压缩到最少。代码本身应当足够清晰让人无需借助注释就能读懂。业内有一条非常经典的原则如果一段代码晦涩到必须靠注释才能看懂那正确的做法是重写它而不是注释它。也就是说解释性注释的存在往往不是注释的问题而是代码设计的问题。与其用注释为糟糕的代码辩解不如动手改善代码本身。下面给出教程中提出的两条具体重构配方。配方一抽出函数factor out functions考虑下面的showPrimes它的内层循环里用一段注释标出检查 i 是否为素数function showPrimes(n) { nextPrime: for (let i 2; i n; i) { // check if i is a prime number for (let j 2; j i; j) { if (i % j 0) continue nextPrime; } alert(i); } }更好的写法是把素数判断抽成独立的isPrime函数让调用处的逻辑一目了然function showPrimes(n) { for (let i 2; i n; i) { if (!isPrime(i)) continue; alert(i); } } function isPrime(n) { for (let i 2; i n; i) { if (n % i 0) return false; } return true; }重构之后注释消失了但代码反而更容易理解——函数本身就变成了注释。这类代码被称为自描述代码self-descriptive从函数名就能读出意图无需逐行追踪实现细节。配方二把长代码片段改写为函数create functions再看一个更长的例子一段用注释分块的流程清单// here we add whiskey for(let i 0; i 10; i) { let drop getWhiskey(); smell(drop); add(drop, glass); } // here we add juice for(let t 0; t 3; t) { let tomato getTomato(); examine(tomato); let juice press(tomato); add(juice, glass); } // ...每块代码都需要一条这里是干什么的注释恰恰说明代码本身缺少可读的结构。将其重构为语义清晰的函数后主流程变成了一行行的自白addWhiskey(glass); addJuice(glass); function addWhiskey(container) { for(let i 0; i 10; i) { let drop getWhiskey(); //... } } function addJuice(container) { for(let t 0; t 3; t) { let tomato getTomato(); //... } }同样的道理函数名自己说明了一切不再需要注释。而且拆分后代码结构更好——每个函数做什么、接收什么参数、返回什么结果都清晰可辨。无法完全避免解释性注释的例外现实中我们不可能完全消灭解释性注释总存在复杂的算法也总有为优化而生的聪明技巧tweaks它们天然难以一眼读懂。但总的原则不变——尽可能让代码简单、自描述把注释留给真正需要它的地方。好注释真正值得写的内容既然解释性注释通常是坏的那么哪些注释是有价值的教程给出四类好注释。1. 描述整体架构注释应该提供代码的上帝视角组件的高层概览、它们之间如何交互、各种场景下的控制流是怎样的。这类架构级注释帮助后人快速建立全局认知。教程还特别提到UMLUnified Modeling Language统一建模语言——一种专门用于绘制高层架构图、解释代码结构的语言值得花时间学习。2. 文档化函数的参数与用法用专门的 JSDoc 语法为函数编写文档说明用法、参数、返回值。典型示例/** * Returns x raised to the n-th power. * * param {number} x The number to raise. * param {number} n The power, must be a natural number. * return {number} x raised to the n-th power. */ function pow(x, n) { ... }这类注释让你不必翻看函数实现就能理解它的用途并正确调用。JSDoc 的价值还体现在工具链上许多编辑器如 JetBrains 的 WebStorm能解析 JSDoc在写代码时提供自动补全autocomplete和自动代码检查有专门的工具如 JSDoc 3可以读取 JSDoc 注释并自动生成 HTML 格式的文档。这意味着注释不只是一段说明文字更是可编译的文档源材料。补充在教程「代码质量」章节的定位中注释与测试、编码风格共同构成了代码可维护性的三块基石。如果说 JSDoc 是函数级的文档那么行为驱动开发BDD中的 spec 则是行为级的文档——详见 1-js/03-code-quality/05-testing-mocha/article.md#L23-L64测试tests、文档documentation和示例examples三位一体很多代码该怎么用的问题用测试表达往往比用注释更可靠、更不易失真。3. 解释为什么用这种方式解决任务已经写出来的内容重要没有写出来的内容可能更重要。代码本身回答不了为什么为什么这个任务偏偏要这样解决当存在多种解法时为什么选这一种尤其是当它不是最直观的那一种时教程给出了一段非常典型的场景推演你或同事隔了一段时间打开自己写的代码觉得它不够优雅——当时的我多么愚蠢现在的我聪明多了——于是用更显然、更正确的方案重写。结果写着写着发现更显然的方案其实有缺陷你甚至隐约记得原因因为很久以前就试过这条路。最终你回退到正确的版本但时间已经浪费掉了。解释为什么的注释非常重要它能帮助后人沿着正确的方向继续开发避免重复踩坑、重复试错。4. 标注代码中的微妙特性及其使用位置如果代码中有任何**微妙subtle且反直觉counter-intuitive**的地方绝对值得加注释。这类注释提醒读者这里有个坑防止后来者在不理解设计意图的情况下顺手修复而引入回归。与教程其他章节的呼应注释在代码质量体系中的位置注释不是孤立的话题它和教程「代码质量」章节的其他主题紧密咬合编码风格Coding Style自描述代码的前提是良好的命名、合理的缩进和克制的嵌套层级。教程在 1-js/03-code-quality/02-coding-style/article.md#L158-L224 中专门演示了如何用continue、提前return等手段减少嵌套层级——代码结构越平坦需要注释打圆场的地方就越少。忍者代码Ninja Code04-ninja-code章节以反讽口吻总结了所有毁掉可读性的技巧——单字母变量、极端缩写、过度抽象的命名、把代码压到最短见 1-js/03-code-quality/04-ninja-code/article.md。那些需要注释才能解释的复杂代码往往正是这些反模式积累的结果。读者不妨把本篇文章与忍者代码对照阅读前者告诉你注释该怎么写后者告诉你什么代码会逼着人写注释。自动化测试Mocha/BDD如前面所述函数的使用说明完全可以用可执行的测试来表达测试即文档详见 1-js/03-code-quality/05-testing-mocha/article.md。总结注释取舍清单一位优秀开发者的重要标志恰恰体现在注释上——包括注释的存在与缺席。好的注释让你能长期维护代码、隔一段时间回来仍能快速上手、并更有效地使用它。应该注释的内容整体架构、高层视角函数的用法参数、返回值重要的解法尤其是当它并非一眼可见时代码中微妙、反直觉的细节及其使用位置。应该避免的注释描述代码如何工作和代码做了什么的解释性注释只有在无法把代码写得足够简单、自描述时才允许出现这类注释。善用自动化文档工具注释还可以被 JSDoc 这类自动文档工具读取用于生成 HTML 或其他格式的文档——把注释从给人看的话升级为可编译的文档资产。最后记住这句话好的代码自带注释坏的代码才需要注释来辩护。当你想写这段代码在做什么的时候先想想——它能不能被重构得更自描述赞分享文档/教程前端【免费下载链接】en.javascript.infoModern JavaScript Tutorial项目地址https://gitcode.com/gh_mirrors/en/en.javascript.info点击查看免费下载相关推荐NSwag代码生成代码模板注释模板内注释最佳实践NSwag代码生成代码模板注释模板内注释最佳实践 NSwag是一个强大的OpenAPI/Swagger代码生成工具能够自动生成客户端代码和API文档。在NS开发工具代码生成API设计3分钟掌握Headlamp让Kubernetes资源监控变得如此简单3分钟掌握Headlamp让Kubernetes资源监控变得如此简单 你是否曾经面对复杂的Kubernetes集群感到手足无措资源使用情况不明、性能瓶颈难寻云原生开发工具如何快速上手FinMem面向AI交易新手的完整入门指南如何快速上手FinMem面向AI交易新手的完整入门指南 FinMem是一款基于大型语言模型LLM的高性能交易代理框架它融合了分层记忆和角色设计能帮助A上一篇实战指南如何高效集成静态二进制工具到你的Node.js项目下一篇原神模型导入神器GIMI3分钟让你成为游戏角色造型师创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
