ESLint no-warning-comments 规则详解用注释规范拦截 TODO、FIXME 与 XXX【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint本篇技术指南以 ESLint 内置规则no-warning-comments为核心讲解如何通过配置terms、location、decoration三个选项在代码评审与发布前自动拦截注释中遗留的 TODO、FIXME、XXX 等警示性词汇并结合仓库源码与测试用例深入剖析其匹配原理大小写不敏感、整词匹配、装饰字符跳过等帮助你在实际项目中快速落地这一注释卫生检查。为什么需要禁用警示性注释开发者在编写尚未完成或需要复查的代码时常常会随手留下注释作为标记。最常见的形式如下// TODO: do something // FIXME: this is not a good idea这些注释的本意是提醒这块代码还没有就绪、还需要复查但问题在于它们很容易被遗忘。代码进入生产环境时这些 TODO/FIXME 往往仍然残留在源码中既不美观也容易掩盖真正的问题。no-warning-comments规则的作用就是把这些警示性词汇当作定时炸弹来排查——只要注释中出现了配置的词汇ESLint 就立即报告错误促使开发者在代码达到生产就绪状态前要么修复代码、要么删除注释。该规则在 lib/rules/no-warning-comments.js 中实现其规则类型为suggestion建议型规则默认不包含在 recommended 配置中需要显式开启见 docs/src/_data/rules.json。Rule Details规则如何工作简单来说这条规则会检查源码中的全部注释凡是注释内容中包含配置项里指定的任一词汇term就会产生一条违规报告。它遍历注释节点的方式非常直接——在Program()节点事件中取出所有注释过滤掉 Shebang 后逐一检查Program() { const comments sourceCode.getAllComments(); comments .filter(token token.type ! Shebang) .forEach(checkComment); }其中checkComment会调用commentContainsWarningTerm对注释内容逐一进行正则测试命中的每个词汇都会触发一条报告消息模板为Unexpected {{matchedTerm}} comment: {{comment}}.一个值得注意的细节是规则会豁免 ESLint 自身的指令注释如/* eslint no-warning-comments: error */。源码中通过astUtils.isDirectiveComment(node)与/\bno-warning-comments\b/u正则双重判断只有当注释本身就是配置本规则的指令时才跳过否则即使是/* eslint one-var: 2 */这类其他规则指令只要其内容命中了配置的词汇例如将eslint或one加入 terms依然会被报告参见 tests/lib/rules/no-warning-comments.js 中的对应测试。isDirectiveComment的实现位于 lib/rules/utils/ast-utils.js。Options三个配置项详解该规则接受一个对象字面量配置共三个选项选项类型默认值说明termsstring[][todo, fixme, xxx]要匹配的警示词汇列表locationstringstart匹配位置可选start注释起始处或anywhere注释任意位置decorationstring[][]当location为start时注释起始处会被忽略的装饰字符terms自定义警示词汇terms是可选的词汇数组默认值为[todo, fixme, xxx]。匹配规则有两条关键约束大小写不敏感fix既能匹配FIX也能匹配fIxMe这类混合大小写写法。测试用例中专门验证了// any fIxMe、/* any FIXME */均会命中见 tests/lib/rules/no-warning-comments.js整词匹配word boundaryfix可以匹配FIX但不会匹配fixing或affix这类包含该词作为子串的单词。词汇还支持由多个单词组成例如配置really bad idea就可以匹配包含这一整句的注释。location匹配位置location默认值为start即只检查注释的起始位置。这里的起始指的是跳过空白、换行以及decoration中指定的字符之后的第一处内容。另一个可选值是anywhere此时会在注释的任意位置查找词汇。decoration起始装饰字符decoration默认为[]仅在location: start时生效。许多开发者喜欢用连续的星号、斜杠等字符美化注释如/***** TODO ... *****/或 JSDoc 风格的多行注释/** ... */这些装饰性字符如果不忽略会干扰start位置对词汇的识别。配置decoration后注释起始处的任意空白序列与这些字符都会被跳过。当location为anywhere时此选项会被忽略。默认配置下的代码示例以下代码演示了默认配置{ terms: [todo, fixme, xxx], location: start }的行为。不正确的代码示例应当被报告/*eslint no-warning-comments: error*/ /* FIXME */ function callback(err, results) { if (err) { console.error(err); return; } // TODO }上面的多行注释以FIXME开头、行注释以TODO开头两处都会命中默认词汇因此都被判为错误。正确的代码示例应当通过检查/*eslint no-warning-comments: error*/ function callback(err, results) { if (err) { console.error(err); return; } // NOT READY FOR PRIME TIME // but too bad, it is not a predefined warning term }这里NOT READY FOR PRIME TIME并不在默认的terms列表中且默认location: start模式下位于注释中段的内容本来也不会被检查因此代码通过检查。组合 terms 与 location匹配任意位置将terms与location: anywhere组合可以做到在注释全文中查找警示词汇适合对注释质量要求更严格的团队。不正确的代码示例配置为{ terms: [todo, fixme, any other term], location: anywhere }/*eslint no-warning-comments: [error, { terms: [todo, fixme, any other term], location: anywhere }]*/ // TODO: this // todo: this too // Even this: TODO /* * The same goes for this TODO comment * Or a fixme * as well as any other term */// TODO: this与// todo: this too中的词汇位于注释开头// Even this: TODO中的词汇位于注释末尾多行块注释中的TODO、fixme、any other term分布在正文各处——由于anywhere模式会在任意位置查找以上全部会被报告。正确的代码示例同样的配置/*eslint no-warning-comments: [error, { terms: [todo, fixme, any other term], location: anywhere }]*/ // This is to do // even not any other term // any other terminal /* * The same goes for block comments * with any other interesting term * or fix me this */这里的关键在于整词匹配的边界行为to do中间有空格不是一个完整词不会命中todoany other term中间的空格序列被正则压缩处理源码中以/\s/u折叠空白但term与any other之间被空白隔开并非连续的any other term因此不命中any other terminal中any other后面紧跟terminal而不是term整词边界使term无法命中fix me this中fix与me被空格分隔不是fixme注意location: anywhere模式下decoration选项会被忽略。Decoration Characters处理装饰字符当location为默认的start时decoration可以指定一组在注释起始处被忽略的字符。不正确的代码示例配置为{ decoration: [*] }/*eslint no-warning-comments: [error, { decoration: [*] }]*/ //***** todo decorative asterisks are ignored *****// /** * TODO new lines and asterisks are also ignored in block comments. */第一条注释虽然以//*****开头但星号作为装饰字符被忽略后面的todo依然会被定位到注释起始处第二条块注释起始处的换行、星号同样被跳过TODO仍然命中。不正确的代码示例配置为{ decoration: [/, *] }/*eslint no-warning-comments: [error, { decoration: [/, *] }]*/ ////// TODO decorative slashes and whitespace are ignored ////// //***** todo decorative asterisks are also ignored *****// /** * TODO new lines are also ignored in block comments. */当同时把/与*加入decoration后//////这类斜杠装饰、*****这类星号装饰以及换行都会被忽略注释起始处的词汇照样命中。正确的代码示例配置为{ decoration: [/, *] }/*eslint no-warning-comments: [error, { decoration: [/, *] }]*/ //!TODO preceded by non-decoration character /** *!TODO preceded by non-decoration character in a block comment */!不在decoration列表中也不是空白字符因此它无法被跳过导致TODO不再位于起始处两条注释都不会被报告。这正是decoration机制的边界所在起始处只能被空白与显式声明的装饰字符跳过。源码级原理正则如何生成为了深入理解上述行为我们来看规则核心的convertToRegExp函数见 lib/rules/no-warning-comments.js。每个配置的词汇都会被转成一个正则location: start时前缀为^[\sdecoration字符]*即允许起始处出现任意空白与装饰字符然后紧跟转义后的词汇本体location: anywhere时若词汇以单词字符开头则前缀为\b词边界若以单词字符结尾则后缀为\b正则标志固定为iu——i提供大小写不敏感u提供 Unicode 大小写折叠这正是fIxMe、FIX都能被识别的原因词汇中的正则特殊字符会先经escape-string-regexp转义因此把[litera|$]、[aeiou]这类含特殊字符的字符串当作词汇也完全安全测试见 tests/lib/rules/no-warning-comments.js 与 tests/lib/rules/no-warning-comments.js。例如默认配置下TODO的匹配正则形如/^[\s]*todo\b/iu配置decoration: [*]后则变为/^[\s\*]*todo\b/iu。另外报告消息中的注释内容有一个 40 字符的展示上限源码常量CHAR_LIMIT 40报告时会按空白分词拼接注释文本超过 40 个字符的部分用...省略。这在超长或含多行内容的注释上体现得很明显例如测试中// TODO: something really longer than 40 characters的报告内容被截断为TODO: something really longer than 40...超长 URL 注释甚至直接显示为...见 tests/lib/rules/no-warning-comments.js。如何开启该规则由于该规则不在eslint:recommended中需要手动在配置文件里开启。在 flat config新版 ESLint 默认中// eslint.config.js export default [ { rules: { no-warning-comments: error, // 自定义配置示例 no-warning-comments: [error, { terms: [todo, fixme, xxx, hack], location: start, decoration: [*, /] }] } } ];在旧的 eslintrc 风格配置中{ rules: { no-warning-comments: [error, { terms: [todo, fixme, xxx], location: anywhere }] } }严重级别同样支持warn与error。该规则的schema校验见 lib/rules/no-warning-comments.js还约束了location只能是start或anywheredecoration中每个字符必须是单个非空白字符pattern: ^\\S$、至少 1 项且不能重复。需要特别注意的是由于decoration的minItems: 1约束传空数组[]会被判定为配置非法不配置该选项时应直接省略。When Not To Use It何时不该用no-warning-comments并非放之四海而皆准文档明确给出了两类不适用场景历史包袱过重的大型代码库如果代码库在开发时没有禁止使用警示词汇的约定历史遗留的 TODO/FIXME 可能多达数百条。此时一次性开启会产生海量警告/错误如果你没有时间全部修复反而会掩盖其他更有价值的警告或让人对警告脱敏、不再关注。词汇本身过于常用同理不要把注释语言里高频出现的词汇配置进terms。例如中文注释里常见的待办问题等泛化词或与业务领域强相关、必然反复出现的词配置进去只会导致噪音。建议的落地方式是从warn级别开始配合location: start与保守的terms列表逐步推行待存量注释清理完毕后再升级为error。小结no-warning-comments用一套极其轻量的正则机制把注释卫生纳入自动化检查管线默认拦截todo/fixme/xxx支持大小写不敏感与整词匹配支持在start/anywhere两种位置检查并可用decoration优雅处理各种装饰性注释风格。配合源码中 lib/rules/no-warning-comments.js 的正则生成逻辑与 tests/lib/rules/no-warning-comments.js 中 600 余行的完整测试用例你可以精准预测它对任何注释的判定结果将其作为代码评审前的一道自动防线。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考