ESLint multiline-comment-style 规则完全指南统一多行注释风格【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslintESLint 内置的multiline-comment-style规则用于强制多行注释采用统一的书写风格解决不同风格指南对跨行注释到底该用块注释还是连续行注释的分歧。本指南基于本仓库中的官方规则文档与源码实现完整讲解三种可用选项starred-block、bare-block、separate-lines的语义、配置方式、自动修复行为、JSDoc 与指令注释的特殊处理以及该规则从 ESLint 核心迁移到 ESLint Stylistic 后的替代方案。规则背景为什么要统一多行注释风格许多团队的风格指南对跨越多行的注释有明确要求有些风格指南偏好用单个块注释/* ... */承载多行内容另一些则偏好用连续的多行注释// ...。若代码库中两种风格混用会显著降低可读性与可维护性。multiline-comment-style规则正是为此设计它强制代码中的多行注释采用统一风格且在多数场景下支持--fix自动修复规则的meta.fixable声明为whitespace见 lib/rules/multiline-comment-style.js。在 lib/rules/index.js 中以惰性加载方式注册属于suggestion类型规则未列入recommended集合在 tests/conf/eslint-recommended.js 中未出现该规则。配置方式该规则接受一个字符串选项可选值如下表所示选项值默认值语义starred-block✅ 默认禁止连续行注释要求使用块注释且要求块注释每行前有对齐的*星号bare-block—禁止连续行注释要求使用块注释但禁止块注释每行前出现*星号忽略 JSDoc 注释separate-lines—禁止块注释要求使用连续行注释默认忽略 JSDoc 注释可通过checkJSDoc: true将其纳入检查此外该规则始终忽略指令注释directive comments例如/* eslint-disable */、/* global foo */等。在 flat config 中的典型配置写法如下// eslint.config.js export default [ { rules: { multiline-comment-style: [error, starred-block], // 或 multiline-comment-style: [error, bare-block], // 或 multiline-comment-style: [error, separate-lines], // 带 checkJSDoc 选项仅 separate-lines 支持 multiline-comment-style: [error, separate-lines, { checkJSDoc: true }] } } ];规则的模式schema由两个分支构成lib/rules/multiline-comment-style.js第一个分支只允许starred-block或bare-block字符串不接受额外参数第二个分支只允许separate-lines并可附带一个仅含checkJSDocboolean的对象且不允许其他额外属性。选项一starred-block默认starred-block要求多行注释必须是块注释禁止用连续的//行注释同时块注释必须是星号对齐形式——每个内容行以对齐的*开头/*后与*/前都要有换行。以下代码在该选项下被判定为不正确/* eslint multiline-comment-style: [error, starred-block] */ // this line // calls foo() foo(); /* this line calls foo() */ foo(); /* this comment * is missing a newline after /* */ /* * this comment * is missing a newline at the end */ /* * the star in this line should have a space before it */ /* * the star on the following line should have a space before it */以下代码在该选项下被判定为正确/* eslint multiline-comment-style: [error, starred-block] */ /* * this line * calls foo() */ foo(); // single-line comment注意单行注释// single-line comment不受影响规则只针对跨越多行的注释。选项二bare-blockbare-block同样禁止连续行注释、要求使用块注释但要求块注释不能以每行一个*的星号形式书写——即希望内容行直接从缩进后开始。JSDoc 注释/** ... */在此选项下被忽略不会被转换或报错。以下代码在该选项下被判定为不正确/* eslint multiline-comment-style: [error, bare-block] */ // this line // calls foo() foo(); /* * this line * calls foo() */ foo();以下代码在该选项下被判定为正确/* eslint multiline-comment-style: [error, bare-block] */ /* this line calls foo() */ foo();从源码看lib/rules/multiline-comment-style.jsbare-block检查器有两类行为当注释组由多个连续行注释组成时报告expectedBlockExpected a block comment instead of consecutive line comments.并将其自动合并为一个裸块注释当注释组是带星号的块注释即isStarredBlockComment判定为真时报告expectedBareBlockExpected a block comment without padding stars.并去除每行的*。自动修复时会调用convertToBlocklib/rules/multiline-comment-style.js把内容行以/*开头、后续行按注释起始缩进对齐、*/结尾的方式重组因此即使原文中各行缩进不齐如测试用例里// foo、// bar混排修复后也能得到规整的裸块注释参见 tests/lib/rules/multiline-comment-style.js。选项三separate-linesseparate-lines与前面两个选项方向相反禁止块注释要求多行注释拆分为连续的行注释。默认忽略 JSDoc 注释设置checkJSDoc: true后JSDoc 注释也会被一并拆分。以下代码在该选项下被判定为不正确未设置checkJSDoc/* eslint multiline-comment-style: [error, separate-lines] */ /* This line calls foo() */ foo(); /* * This line * calls foo() */ foo();以下代码在该选项下被判定为正确/* eslint multiline-comment-style: [error, separate-lines] */ // This line // calls foo() foo();开启checkJSDoc后JSDoc 块注释也会被检查以下代码在separate-lines且checkJSDoc: true时被判定为不正确/* eslint multiline-comment-style: [error, separate-lines, { checkJSDoc: true }] */ /** * I am a JSDoc comment * and Im not allowed */ foo();以下代码在separate-lines且checkJSDoc: true时被判定为正确/* eslint multiline-comment-style: [error, separate-lines, { checkJSDoc: true }] */ // I am a JSDoc comment // and Im not allowed foo();指令注释与 JSDoc 的特殊处理指令注释总是被忽略无论选择哪个选项指令注释如/* eslint-disable */、/* eslint semi: error */、/* global foo */都不会被该规则报错或转换。实现上规则在收集注释后先用astUtils.COMMENTS_IGNORE_PATTERN过滤lib/rules/multiline-comment-style.js该模式定义于 lib/rules/utils/ast-utils.jsconst COMMENTS_IGNORE_PATTERN /^\s*(?:eslint|jshint\s|jslint\s|istanbul\s|globals?\s|exported\s|jscs)/u;这也解释了测试中为什么多行配置指令如/* eslint semi: [ error ] */在任意选项下均为合法见 tests/lib/rules/multiline-comment-style.js。JSDoc 的识别与豁免规则内置了 JSDoc 注释识别函数isJSDocCommentlib/rules/multiline-comment-style.js其判定条件为注释值第一行是*中间每行以空白加空格开头最后一行只有空白——即典型的/** ... */文档注释形态。基于此bare-block与separate-lines在默认情况下都会跳过 JSDoc 注释separate-lines只有在checkJSDoc: true时才将 JSDoc 纳入检查lib/rules/multiline-comment-style.js。源码级剖析规则如何工作注释分组逻辑规则只在Program节点上运行一次lib/rules/multiline-comment-style.js流程如下通过sourceCode.getAllComments()获取全部注释过滤掉 Shebang 注释与指令注释只保留独立成行的注释即其前面的 token 与它不在同一行避免误伤行内注释将连续的行注释合并成注释组判断依据当前行注释的前一个 token 恰好是上一条行注释且结束行与当前注释开始行相邻过滤掉单行注释开始行 结束行只处理真正的多行注释将每个注释组交给所选选项对应的检查器处理。例如测试用例中两段被空行隔开的连续行注释会各自成组、分别报错并分别修复见 tests/lib/rules/multiline-comment-style.js。三种注释形态的识别与互相转换规则通过getCommentLines统一提取注释内容行lib/rules/multiline-comment-style.js并根据当前形态调用不同的处理函数处理函数适用形态行为processSeparateLineComments连续行注释若所有非空行都有前导空格则去掉每行第一个空格使内容对齐processStarredBlockComment星号块注释去掉首尾空行与每行的*前缀若各行都带空格则连空格一起去掉processBareBlockComment裸块注释以注释起始缩进为基准计算最浅缩进行并据此规整各行偏移对应的转换函数lib/rules/multiline-comment-style.js则负责把提取出的内容行组装回目标形态convertToStarredBlock生成/* 每行{缩进} * {内容}*/convertToSeparateLines生成// {内容}序列convertToBlock生成/* {内容} */的裸块形态。这正是--fix能够精确重排注释缩进的底层实现。报告的消息标识规则暴露了 7 个消息标识lib/rules/multiline-comment-style.js便于配置自定义消息或定位问题expectedBlock期望用块注释替代连续行注释starred-block/bare-blockexpectedBareBlock期望不含星号的裸块注释startNewline/*后缺少换行endNewline*/前缺少换行missingStar某行缺少行首*alignment*未与注释起始对齐expectedLines期望用连续行注释替代块注释separate-lines自动修复的边界需要留意的是规则不会在所有情况下都给出修复方案。例如当行注释内容以/开头如//foo、///barstarred-block会报告expectedBlock但不提供修复返回null因为转换可能产生有歧义的/*/...*/内容见 lib/rules/multiline-comment-style.js当注释内容包含*/序列时starred-block会跳过整个注释组以免破坏注释结构lib/rules/multiline-comment-style.jsseparate-lines在块注释后面紧跟同一行代码时如/* ... */ foo;会跳过避免拆分后改变代码语义lib/rules/multiline-comment-style.js。这些边界行为在测试套件 tests/lib/rules/multiline-comment-style.js共 1451 行、覆盖三个选项的大量正反用例中有完整验证例如output: null表示报告但不可修复。何时不使用此规则如果团队不打算强制多行注释的书写风格可以直接关闭该规则multiline-comment-style: off迁移提示规则的弃用状态从源码元信息可知lib/rules/multiline-comment-style.js该规则自 ESLintv9.3.0起被标记为弃用deprecatedSince: 9.3.0并计划在v11.0.0前移除availableUntil: 11.0.0原因是 ESLint 官方正在将格式化类规则移出核心。弃用后的维护方为 ESLint Stylistic对应替代插件为stylistic/eslint-plugin中的同名规则multiline-comment-style。因此对于新项目建议直接使用 ESLint Stylistic 提供该规则对于存量项目可参考本指南的三种选项语义在迁移时保持配置项与期望风格不变。本仓库中的 官方规则文档 与 规则源码 仍可作为理解该规则行为的第一手资料。总结multiline-comment-style用三个互斥的选项starred-block、bare-block、separate-lines帮助团队把多行注释收敛为同一种形态并配套了相当完善的自动修复能力星号对齐、换行补齐、缩进规整、JSDoc 豁免与指令注释忽略等细节均由源码中的专用辅助函数逐一处理。理解这些底层行为既能准确预测该规则在真实代码上的报告与修复结果也能在迁移到 ESLint Stylistic 时无缝沿用既有的风格决策。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考