埃斯林特- 插座- 清洁码
ESLint规则来源于 清洁码 由罗伯特·C·马丁(Robert C.
每个规则都映射到一个编号的书规则(第17章"口味和Heuristics",外加从第3,7和9章中选取的规则),每个参考文献都保存在规则元数据中(第17章)meta.docs.cleanCodeId)),所以一个小报告直接指向了这本书.
- 44个ESLint规则,每本书规则1个
- 第17章的66个编号的休眠:39个自动化,27个记录表明无法静态地探测(见 第17章 测绘(中文(简体) )
- ESLint 9 平面配置, TypeScript 友好, 双重无害环境管理/ CJS 构建
为什么会这样
我写这个插件是因为我一直想知道 遵守所有清洁守则规则有多难。 事实证明,对于人类来说是困难的,对于特工来说是微不足道的——所以现在,你的特工们与其遵守规则,不如跟着他们为你. 指着他们 strict,或 strictest 如果你感到勇敢, 他们会写出干净,一致, 严格规则的代码, 它会让即使是最活泼的机器人哭出 一致和干净的快乐的眼泪.
安装
npm install --save-dev eslint @george2f/eslint-plugin-clean-code
需要 ESLint QQ 8.57 (8.57, 9.x和 10.x 支持; 零运行时间依赖性). 这个 configs.recommended 编号 : configs.strict 出口为平面配置对象;关于遗产 .eslintrc 设置, 注册插件 (plugins: ['@george2f/clean-code'])并手动启用规则.
使用量
// eslint.config.js
import cleanCode from '@george2f/eslint-plugin-clean-code';
export default [
cleanCode.configs.recommended, // 12 high-confidence rules, all errors
// cleanCode.configs.strict, // all 44 rules; static = error, heuristic = warn
// cleanCode.configs.strictest, // all 44 rules at error, heuristics included
];
或单独选择规则:
import cleanCode from '@george2f/eslint-plugin-clean-code';
export default [
{
plugins: { 'clean-code': cleanCode },
rules: {
'clean-code/max-arguments': ['error', { max: 4 }],
'clean-code/law-of-demeter': ['warn', { maxChainLength: 2 }],
},
},
];
配置
| 配置 | 规则 | 严重性 | 意图 |
|---|---|---|---|
clean-code/recommended | 第12条 | error | 可靠的AST检测,低假阳性率 |
clean-code/strict | 第44条 | error 静态/ warn 高压 | 所有的一切,包括有观点的修养 |
clean-code/strictest | 第44条 | error | 所有错误, 都包含弹性; 期望调用选项 |
12个 recommended 规则 : max-arguments, (中文(简体) ), no-commented-out-code, (中文(简体) ), no-dead-code, (中文(简体) ), no-encodings, (中文(简体) ), no-flag-arguments, (中文(简体) ), no-magic-numbers, (中文(简体) ), no-negative-conditionals, (中文(简体) ), no-overridden-safeties, (中文(简体) ), no-pass-null, (中文(简体) ), no-return-null, (中文(简体) ), no-skipped-tests, (中文(简体) ), no-todo-tests。 。 。 .
规则等级
- 静态 - 可靠的AST探测器;船只装入
recommended。 。 。 . - 高压 带有可配置选项的以阈值为基础的探测;
warn默认在strict财务报告和审定财务报表error内strictest。期望在真实的代码库中调制选项或禁用少数选项;每个Heuristic都有文件记录的选项集(参见 选项) (中文(简体) ).
机器可读规则目录
出版的邮包船 rules.json (作为 @george2f/eslint-plugin-clean-code/rules.json: 每一个带有其书名ID,分级,配置成员,默认选项,JSON schema,自定义/建议旗,以及docs链接的规则. 用于工具与编码代理.
第17章:气味和热度
图例: static 船舶在 recommended • 妇女 heuristic 船舶在 strict 作为警告 doc-only 故意不执行(说明理由)——没有假规则.
评论
| 身份证 | 书本规则 | 规则 | 仁爱 |
|---|---|---|---|
| C1 级 | 信息不当 | clean-code/no-inappropriate-comments | 高压 |
| C2级 | 过时注释 | —— 说 | 仅 doc- —— 需要语义学上的知识 代码 |
| C3 数据 | 冗余注释 | clean-code/no-redundant-comments | 高压 |
| C4级 | 错误的书面评论 | —— 说 | 只有医生——主观;手动审查 |
| 第5类 | 注释出代码 | clean-code/no-commented-out-code | 静态 |
环境
| 身份证 | 书本规则 | 规则 | 仁爱 |
|---|---|---|---|
| 页:1 | 构建需要更多的步骤 | —— 说 | 只有医生——保留一个 npm run build; 构建工具,而非线条 |
| E2级 | 测试需要更多的步骤 | —— 说 | 只有医生——保留一个 npm test; 测试工具,而非用意 |
职能
| 身份证 | 书本规则 | 规则 | 仁爱 |
|---|---|---|---|
| F1 导弹 | 参数太多 | clean-code/max-arguments | 静态 |
| F2 请检查DATE=中的日期值 (帮助) F2 | 输出参数 | clean-code/no-output-arguments | 高压 |
| F3 联合国 | 旗帜参数 | clean-code/no-flag-arguments | 静态 |
| F4 联合国 | 已死函数 | clean-code/no-dead-functions | 柔和主义——只有同一份文件 |
常规
| 身份证 | 书本规则 | 规则 | 仁爱 |
|---|---|---|---|
| 集团1 | 一个源文件中的多语言 | clean-code/no-multiple-languages | 高压 |
| G2型 | 明显的行为未执行 | —— 说 | 只有医生——需要意图;使用TDD和审查 |
| G3集团 | 边界上的不正确行为 | —— 说 | 仅 doc- -- 边界测试( T5 ), 不用 lint |
| G4集团 | 安全无虞 | clean-code/no-overridden-safeties | 静态 |
| 5国集团 | 复制 | clean-code/no-duplication | 高压- 相同的文件; 使用 jscpd 用于跨文件克隆 |
| 6国集团 | 抽象度错误的代码 | —— 说 | 只有医生——设计判断 |
| 7国集团 | 取决于衍生物的基类 | clean-code/no-base-class-knowing-derivatives | 高压 |
| 8国集团 | 信息过多 | clean-code/limited-public-api | 高压 |
| 9国集团 | 死亡代码 | clean-code/no-dead-code | 静态 |
| 10国集团 | 垂直分离 | clean-code/declaration-proximity | 高压 |
| 11国集团 | 不一致 | —— 说 | 只有 doc —— 使用 Pretier 和 共享配置 |
| 12国集团 | 克吕特 | clean-code/no-clutter | 高压 |
| 13国集团 | 人工耦合 | —— 说 | 只有医生——设计判断 |
| 14国集团 | 特性条目 | clean-code/no-feature-envy | 高压 |
| 15国集团 | 选择参数 | clean-code/no-selector-arguments | 高压 |
| 16国集团 | 淫荡的意向 | clean-code/no-obscured-intent | 高压 |
| 17国集团 | 错位责任 | —— 说 | 只有医生——设计判断 |
| 18国集团 | 不适当的静态 | clean-code/no-inappropriate-statics | 高压 |
| 19国集团 | 使用解释变量 | clean-code/use-explanatory-variables | 高压 |
| 20国集团 | 函数名称应该说它们做什么 | clean-code/function-names-say-what-they-do | 高压 |
| 21国集团 | 理解算法 | —— 说 | 只有医生——需要理解;审查 |
| 22国集团 | 建立逻辑依赖 | —— 说 | 只有医生——设计判断 |
| 23国集团 | 偏好多态化到 If/Else 或 switch/ Case | clean-code/prefer-polymorphism | 高压 |
| 24国集团 | 遵守标准公约 | —— 说 | 只有doc——将公约编码为规则 |
| 25国集团 | 将魔法数字替换为命名的常数 | clean-code/no-magic-numbers | 静态 |
| 26国集团 | 精细 | clean-code/be-precise | 高压 |
| 27国集团 | 《公约》结构 | —— 说 | 只有医生——设计判断 |
| 28国集团 | 封装条件 | clean-code/encapsulate-conditionals | 高压 |
| 29国集团 | 避免负条件 | clean-code/no-negative-conditionals | 静态 |
| 30国集团 | 函数应该做一个东西 | clean-code/function-does-one-thing | 高压 |
| 31国集团 | 隐藏时间交错 | —— 说 | 只有 doc —— 需要运行时命令知识 |
| 32国集团 | 不要随意 | —— 说 | 仅 doc- 样式一致性; 使用共享配置 |
| 33国集团 | 封装边界条件 | clean-code/encapsulate-boundaries | 高压 |
| 34国集团 | 函数应仅发送一个抽象级 | clean-code/one-level-of-abstraction | 高压 |
| 35国集团 | 将可配置数据保持在高水平 | —— 说 | 只有医生——安置判决 |
| 36国集团 | 避免通航(Demeter法) | clean-code/law-of-demeter | 高压 |
Java 区域
| 身份证 | 书本规则 | 规则 | 仁爱 |
|---|---|---|---|
| J1 数据 | 使用通配符避免长导入列表 | clean-code/prefer-namespace-imports | 柔和主义——与树相搏;有意选择 |
| 联合来文2 | 不要继承常数 | clean-code/no-inherited-constants | 高压 |
| J3 数据 | 常数对 Enums | —— 说 | 只有 doc —— TypeScript idioms 与 Java 不同 |
名称
| 身份证 | 书本规则 | 规则 | 仁爱 |
|---|---|---|---|
| 编号1 | 选择描述性名称 | clean-code/descriptive-names | 高压 |
| 编号2 | 在抽象的适当级别选择名称 | —— 说 | 只有doc——需要域知识 |
| 编号3 | 可能时使用标准名称 | —— 说 | 仅 doc- 需要项目词典 |
| 无 | 无矛盾名称 | clean-code/no-ambiguous-names | 高压 |
| 编号5 | 长范围使用长名 | clean-code/long-names-for-long-scopes | 高压 |
| 编号6 | 避免编码 | clean-code/no-encodings | 静态 |
| 编号7 | 名称应描述边效果 | clean-code/names-describe-side-effects | 高压 |
测试
| 身份证 | 书本规则 | 规则 | 仁爱 |
|---|---|---|---|
| T1 电话 | 测试不足 | —— 说 | 使用覆盖工具(c8, (中文(简体) ), nyc(中文(简体) ) |
| T2 电话 | 使用覆盖工具! | —— 说 | 只有医生——相同 |
| T3 电话 | 不要跳过三次测试 | clean-code/no-skipped-tests | 静态 |
| T4 电话 | 被忽略的测试 是一个关于谜题 | clean-code/no-todo-tests | 静态 |
| T5型导弹 | 测试边界条件 | —— 说 | 仅 doc- -- 测试设计, 而非 lint |
| T6 电话 | 彻底测试 Bugs 附近 | —— 说 | 仅限医生 |
| T7 电话 | 失败模式正在显现 | —— 说 | 仅限医生 |
| T8型导弹 | 测试覆盖模式可以揭示 | —— 说 | 仅限医生 |
| T9 电话 | 测试应该快速 | —— 说 | 仅限医生 |
章衍生出的规则
第17章中未列出的前面各章中的规则:
| 章 次 页 次 | 原则 | 规则 | 仁爱 |
|---|---|---|---|
| 3个 | 命令查询分离 | clean-code/command-query-separation | 高压 |
| 3个 | 优先选择返回出错代码的例外 | clean-code/prefer-exceptions-over-error-codes | 高压 |
| 第7条 | 不要还原 | clean-code/no-return-null | 静态 |
| 第7条 | 别传努尔 | clean-code/no-pass-null | 静态 |
| 第9条 | 每一次测试一次 | clean-code/one-assertion-per-test | 高压 |
没有通融规则的章节原则(有文献记载,按设计): Boy Scout Rule, KISS, 找到根源, 使用依赖性注入, 单独多行码, 防止过度配置, 偏好专有值对象于原始人, 隐藏内部结构, 偏好数据结构, F. I. R. S. T. (部分被覆盖) no-skipped-tests 财务报告和审定财务报表 one-assertion-per-test),以及所有格式化规则(使用Pretier).
选项
每个规则都接受一个选项对象;部分选项与下面的默认合并.
| 规则 | 默认 |
|---|---|
max-arguments | { max: 3 } |
no-dead-code | { ignoreNames: [], ignoreRestSiblings: true } |
no-magic-numbers | { ignore: [0, 1, 2, -1], ignoreDefaultValues: true, ignoreArrayIndexes: false, ignoreEnums: true } |
no-pass-null | { ignoreCallees: ['^use[A-Z]'] } |
no-return-null | { allowNullableReturnType: true } |
no-skipped-tests | { testFunctions: ['it', 'test', 'describe', 'context', 'suite', 'specify'] } |
no-todo-tests | { testFunctions: ['it', 'test', 'specify'] } |
no-inappropriate-comments | { patterns: [] } (外部正则出处) |
no-redundant-comments | —— 说 |
no-output-arguments | —— 说 |
no-dead-functions | { allow: [] } |
function-does-one-thing | { maxStatements: 20, maxLines: 30 } |
one-level-of-abstraction | { minLowLevelOps: 3, minHighLevelCalls: 2 } |
no-multiple-languages | { checkSql: true, checkHtml: true } |
no-duplication | { minStatements: 4, minNodes: 25 } |
limited-public-api | { maxClassMembers: 25, maxExports: 50 } |
declaration-proximity | { maxDistance: 15 } |
no-feature-envy | { minimumAccesses: 4 } |
no-selector-arguments | { minComparisons: 2 } |
use-explanatory-variables | { minComplexLookups: 1 } |
function-names-say-what-they-do | { forbidden: ['handle', 'process', 'manage', 'util', 'utils', 'misc', 'stuff', 'thing', 'data', 'info', 'temp', 'tmp', 'foo', 'bar', 'baz', 'func', 'fn', 'callback', 'cb', 'do', 'perform', 'execute', 'handleData', 'doStuff', 'doWork', 'doIt'] } |
prefer-polymorphism | { maxSwitchCases: 4, maxIfElseBranches: 5 } |
encapsulate-conditionals | { maxLogicalOperators: 2 } |
law-of-demeter | { maxChainLength: 3, allow: [] } |
descriptive-names | { allow: ['i', 'j', 'k', 'x', 'y', 'z', 'e', '_'], forbidden: ['data', 'info', 'stuff', 'thing', 'temp', 'tmp', 'foo', 'bar', 'baz', 'obj', 'arr', 'val', 'utils', 'misc'] } |
no-ambiguous-names | { confusingNames: ['l', 'O', 'I'] } |
long-names-for-long-scopes | { minLength: 3, allow: ['i', 'j', 'k', 'x', 'y', 'z', 'e', '_', 'it'] } |
no-encodings | { patterns: [], typePrefixes: false } |
names-describe-side-effects | { prefixes: ['get', 'is', 'has', 'find'] } |
prefer-namespace-imports | { maxNamedImports: 10 } |
one-assertion-per-test | { maxAssertions: 1, testFunctions: ['it', 'test'] } |
no-overridden-safeties | { allowEmptyCatch: false, allowTsIgnore: false, requireDisableReason: true } |
上文未列出的规则没有选择权.
max-arguments 将每个绑定物分别计算为分解图案,重复为嵌入图案;剩余绑定物计为一. function f({ a, b, c, d }) 因此,有四个论点.
自动修正和建议
三个规则支持 eslint --fix数字 :
| 规则 | 自动修正 |
|---|---|
no-negative-conditionals (29国集团) | 交换分枝并取出 ! (连续否定语如: !! 在一张通行证内删除) |
no-clutter (12国集团) | 删除出错 ; 语句,将空控流机构转换为 {},删除无用的构造器 |
no-dead-code (G9,仅进口) | 删除未使用的导入描述符并重写声明(或发出) import "mod"; 保留模块副作用) |
编辑器快速修补(建议——每起事件应用,从未使用过) --fix:
| 规则 | 建议 |
|---|---|
| C5 / C1 / C3 注释规则 | 删除注释 |
no-dead-code (9国集团) | 删除未使用的变量声明(仅在初始化器没有副作用时),或删除无法获取的语句 |
no-dead-functions (F4级) | 删除已死函数或私有方法 |
no-skipped-tests (图3) | 解开测试 |
no-clutter (12国集团) | 删除 debugger 语句 |
no-overridden-safeties (四国集团) | 替换 @ts-ignore 与 @ts-expect-error |
与 ESLint 核心规则重叠
一些规则有意重新执行与核心规则或其他通俗规则相重叠的书语义. 只允许一方避免重复报告 :
| 此插件 | 重叠与 |
|---|---|
max-arguments (F1级) | 核心项目 max-params |
no-magic-numbers (25国集团) | 核心项目 no-magic-numbers |
no-negative-conditionals (29国集团) | 核心项目 no-negated-condition |
no-dead-code (9国集团) | 核心项目 no-unused-vars, (中文(简体) ), no-unreachable, (中文(简体) ), @typescript-eslint/no-unused-vars |
no-obscured-intent (16国集团) | 核心项目 no-nested-ternary, (中文(简体) ), no-sequences, (中文(简体) ), no-cond-assign |
no-skipped-tests (图3) | jest/no-disabled-tests, (中文(简体) ), vitest/no-disabled-tests |
no-overridden-safeties (四国集团) | @typescript-eslint/ban-ts-comment (计: @ts-ignore(中文(简体) ) |
高血压
高压规则是判决要求的近似值. 每个阈值都是一个选项;如果一个热度在你的代码库中是响亮的,首先调整其选项,然后用一个解释原因的评论来禁用它——这正是书中认可的那种评论.
发展
npm install
npm test # vitest + ESLint RuleTester (44 rule suites + integration test)
npm run typecheck # tsc --noEmit
npm run build # tsup -> dist (minified ESM + CJS + d.ts + rules.json)
npm run verify:dist # checks the built bundles (rule count, configs, meta)
npm run lint # builds, then lints the plugin with its own rules + typescript-eslint
每一个规则都生活在 src/rules/<rule-name>.ts 与合用地点 .test.ts。书名参考文献在 meta.docs.cleanCodeId 财务报告和审定财务报表 meta.docs.cleanCodeRule. 编码代理的撰稿人笔记 一般事务人员(其他职等)。 。 。 .
释放
用 npm 信任的出版方式( OIDC) 从 CI 发布; 任何地方都不存储任何符号 .
- 弹出
version内package.json并添加更改日志条目 - 提交,然后标记并按:
git tag vX.Y.Z && git push origin vX.Y.Z .github/workflows/release.ymllints,测试,从匹配的 changlog 部分创建出 GitHub 发布器,并发布出处
一次性设置: 在 npmjs.com 上, 将软件包可信任的出版商配置为 GitHub Actions, profile George2f/eslint-plugin-clean-code工作流程 release.yml (第一次出版必须在配置后的两天内进行).
许可证
麻省理工学院