In Dart, when do you silence an analyzer finding with an ignore comment, ignore_for_file, analyzer errors: ignore, or analyzer exclude:?

## Four scopes of suppression Every analyzer finding has a **code**: `unused_local_variable`, `dead_code`, `avoid_print`, `deprecated_member_use` and so on. Dart gives you four ways to stop a finding being reported, and they differ in **scope**: | Mechanism | Where it lives | Scope | |---|---|---| | `// ignore: code` | Dart source, above or at the end of a line | that one line | | `// ignore_for_file: code` | Dart source, anywhere in the file | the whole file | | `analyzer: errors: code: ignore` | `analysis_options.yaml` | every file in the package | | `analyzer: exclude: <glob>` | `analysis_options.yaml` | every diagnostic in matching files | The rule of thumb is to use the **narrowest** one that solves the problem, so the exception stays close to the code that needs it and does not hide unrelated findings. ## Line and file comments A line comment either sits on the line above the code or is appended to it: ```dart // ignore: deprecated_member_use final old = legacyApi(); int count = parse(raw); // ignore: unnecessary_cast ``` Both forms take a **comma-separated list** of codes. A file comment has the same syntax with `ignore_for_file`, and applies to the whole file regardless of where it appears, before or after the code in question. The special specifier **`type=lint`** matches every lint rule: ```dart // ignore_for_file: type=lint ``` It does not silence analyzer warnings or errors, only lints. This is the standard header for **generated code**. freezed's generated `.freezed.dart` files start with `// GENERATED CODE - DO NOT MODIFY BY HAND` followed by `// ignore_for_file: type=lint` and a list of specific warning codes, because your project's lint choices should not fire on code nobody edits by hand. ## Package-wide and file-wide switches - **`analyzer: errors: todo: ignore`** removes one code from every file. Use it when the team has decided a diagnostic is not wanted at all. For a lint rule, setting it to `false` under `linter: rules:` has the same practical effect and reads more clearly. - **`analyzer: exclude:`** takes globs relative to the options file, such as `build/**`, `lib/**.g.dart` or `test/_data/**`. It is the bluntest tool: real errors in those files disappear as well. Keep it for build output, vendored code and generated files you never want reported. ## Keeping ignores honest Suppressions rot. A comment that once hid a real finding keeps sitting there after a refactor removes the cause. Two diagnostics help: 1. **`unnecessary_ignore`** (a lint, since Dart 3.8) reports an ignore for a diagnostic that is not produced at that location or in that file. Turn it on to have stale ignores surface as findings. 2. **`duplicate_ignore`** reports a code named twice, for example in both an `ignore` and an `ignore_for_file` comment. Many teams also require a short reason next to each ignore in code review, so the exception documents itself. ## Special cases - **Analyzer plugins** (Dart 3.10+): prefix the code with the plugin name and a slash, as in `// ignore: some_plugin/some_code` or `// ignore_for_file: some_plugin/some_code`. - **`pubspec.yaml`**: since Dart 3.3 a `# ignore: code` comment above a line suppresses a non-error diagnostic there, for example `sort_pub_dependencies` when the `flutter` SDK dependency must stay first. - **`dart fix`** can remove many findings automatically; that tool belongs with the other `dart` commands, but it is often a better answer than an ignore. ## Choosing in practice - A single justified call to a deprecated API: a line `ignore`. - A test file that deliberately prints output: `ignore_for_file: avoid_print`. - A generated part that trips lints: rely on its `type=lint` header, or `exclude:` the glob. - A rule the team rejects: switch it off in `linter: rules:` rather than scattering ignores. - A folder of fixtures or sample data that is not meant to compile cleanly: `exclude:` it, since nothing in it is maintained as code. ## What reviewers look for A suppression is a small, local decision to accept a finding, and code review is where it gets checked. Reviewers typically ask: 1. **Is it precise?** Each comment should name only the codes that line or file really triggers; a long list copied from another file hides more than intended. 2. **Is the scope minimal?** A file-wide ignore to hide one line, or a package-wide `ignore`, is usually a sign the change should be narrower. 3. **Is there a reason?** A short note beside the comment, such as why a deprecated API is still needed, saves the next reader from reverse-engineering it. 4. **Will it expire?** Suppressions tied to a migration should be removed when the migration lands; `unnecessary_ignore` makes the leftovers visible.