禁用注释的合理边界
禁用注释是技术债的一种形式：它让检查在这一处失效。合理的用法是行级禁用并写明原因；文件顶部的整体禁用会让整份文件脱离检查，新引入的问题也一起被放过。团队最好定期统计禁用数量并做审计。
基本信息
| 粒度 | 行级优于块级，块级优于文件级 |
|---|---|
| 写法要求 | 必须写明原因，跟在双连字符之后 |
| 审计手段 | 统计禁用注释数量并按目录排序 |
| 替代方案 | 修根因，或在配置里按路径排除 |
典型使用场景
- 第三方类型无法满足规则：行级禁用并注明原因
- 生成代码或兼容性代码：优先用配置里的路径排除
- 规则本身不适用于某处：考虑改用更合适的规则配置
- 临时绕过：写明关联任务编号并限期清理
- 审计存量：按目录统计禁用数量，多的先治理
判断该不该禁用
- 这条规则是否真的无法满足
- 能否通过调整配置而不是就地禁用解决
- 禁用范围能否缩小到一行
- 是否留下了原因与清理时机
写法示例
写法示例
// eslint-disable-next-line no-console -- 启动横幅必须输出到控制台
console.log(banner);
// 不推荐：文件顶部整份禁用
// /* eslint-disable */粒度与影响
| 粒度 | 影响范围 | 建议 |
|---|---|---|
| 行级 | 单行 | 首选，必须写原因 |
| 块级 | 一段代码 | 谨慎使用，范围尽量小 |
| 文件级 | 整份文件 | 尽量不用，改配置排除更清晰 |
在评审中怎么用
- 看到禁用注释先确认是否尝试过调整配置
- 要求补上原因与关联任务编号
- 定期统计各目录的禁用数量，纳入技术债台账
- 禁用集中出现的模块，说明规则与代码风格不匹配
在评审中的用法：看到禁用注释先问原因与清理时机，缺了这两项就要求补齐再谈合并。
禁用注释也是一种信号：同一处被反复禁用，往往说明规则本身或这段设计需要重新讨论。
文件顶部的整体禁用：整份文件不再受检查，新问题也一并放行。