检查豁免的注释规范
检查豁免指的是在源码中写注释关闭某条检查规则。它本身没有问题，问题在于豁免往往缺少记录：整文件关闭、不写规则名、不写原因、没有跟踪链接，几年后没人知道是否还能删除。可审计的豁免遵循三个要求：尽量按行而不是按文件、注明被关闭的规则名与原因、关联工单或整改时间，并定期复核豁免清单。
三要素
| 范围 | 按行优于按文件，整文件关闭需要更强理由 |
|---|---|
| 说明 | 写明规则名与关闭原因，说明为什么无法整改 |
| 跟踪 | 关联工单编号或整改时间，便于到期复核 |
典型使用场景
- 第三方类型缺失：调用处确需放宽类型检查，按行豁免并注明来源
- 生成代码附近的手写适配：个别规则误报，按行豁免并写原因
- 历史遗留写法：暂时无法整改，写明整改时间与责任人
- 平台差异：某些规则在特定运行环境不适用，豁免时附上环境说明
- 定期治理：按季度清理豁免，已经可以整改的条目直接删除注释
写法对照
写法对照
# 反例：整文件关闭且没有说明
在文件顶部写入禁用全部检查的注释
# 正例：按行关闭，注明规则与原因并附工单号
在目标行上方写注释，指明被关闭的规则名、原因与跟踪编号豁免质量对照
| 写法 | 可审计性 | 后续影响 |
|---|---|---|
| 整文件关闭无原因 | 极低 | 后人不敢删也不知道为何存在 |
| 按行关闭写规则与原因 | 高 | 到期可判断是否仍需保留 |
| 豁免附工单号 | 高 | 可在工单关闭时同步清理 |
| 豁免无期限 | 低 | 临时措施固化，问题永久沉积 |
| 豁免原因写「暂时」 | 低 | 缺少判断依据，无法复核 |
豁免也是技术债条目：建议登记在清单里，随模块重构一并消化。清单可与债务偿还的排期配合，避免豁免只在代码里沉默保留。
优先考虑能否从根本上消除豁免：若某条规则在大量位置误报，先评估规则配置或工具版本是否需要调整，而不是逐处添加豁免注释。
落地检查清单
- 豁免注释包含规则名与原因
- 整文件关闭的条目有额外审批或说明
- 豁免清单定期复核，过期项删除
- 豁免数量作为趋势观察，而不是放任增长