falconGitHub

prefer-commenting-analyzer-ignores

Group
Style
Path
lint/style/prefer-commenting-analyzer-ignores
Default
Off, opt in
Origin
Falcon
Rule
323 of 512

Require explanations for analyzer ignore: and ignore_for_file: comments.

Accept trailing prose (optionally after a second //) or an immediately preceding standalone comment. Blank lines, trailing code comments, empty comments, and other ignore directives do not supply an explanation. Read CST comment tokens so directive-like text in strings is never linted.

ignore-global (bool, default true) skips ignore_for_file: directives.

Invalid

example.dartdart
 // ignore: unused_import
import 'dart:math';

 // ignore_for_file: deprecated_member_use

 // ignore: unused_element, unused_local_variable
void example() {}

// A disconnected explanation.

 // ignore: unused_element
void disconnected() {}

//
 // ignore: unused_element
void emptyComment() {}

final value = 1; // This explains the variable, not the ignore.
 // ignore: unused_element
void trailingComment() {}

 // ignore: unused_element //
void emptyInline() {}

 // ignore: type=lint
void allLints() {}
This analyzer ignore has no explanation. Add trailing explanatory text or an immediately preceding explanation comment.
1 // ignore: unused_import
This analyzer ignore has no explanation. Add trailing explanatory text or an immediately preceding explanation comment.
3
4 // ignore_for_file: deprecated_member_use
This analyzer ignore has no explanation. Add trailing explanatory text or an immediately preceding explanation comment.
5
6 // ignore: unused_element, unused_local_variable
This analyzer ignore has no explanation. Add trailing explanatory text or an immediately preceding explanation comment.
10
11 // ignore: unused_element
This analyzer ignore has no explanation. Add trailing explanatory text or an immediately preceding explanation comment.
14//
15 // ignore: unused_element
This analyzer ignore has no explanation. Add trailing explanatory text or an immediately preceding explanation comment.
18final value = 1; // This explains the variable, not the ignore.
19 // ignore: unused_element
This analyzer ignore has no explanation. Add trailing explanatory text or an immediately preceding explanation comment.
21
22 // ignore: unused_element //
This analyzer ignore has no explanation. Add trailing explanatory text or an immediately preceding explanation comment.
24
25 // ignore: type=lint

Valid

example.dartdart
// Legacy API retained for compatibility.
// ignore_for_file: deprecated_member_use

// Needed for a platform-specific implementation.
// ignore: unused_import
import 'dart:math';

// ignore: unused_element // Called by the platform through reflection.
void reflected() {}

/* The generated visitor requires this hook. */
// ignore: unused_element
void hook() {}

/// Entry point invoked externally.
// ignore: unused_element
void entryPoint() {}

// ignore: unused_element This entry point is invoked externally.
void inlineProse() {}

// ignore: unused_element, long-method This generated hook needs both exceptions.
void multipleCodes() {}

// ignore: type=lint Compatibility shim maintained for an external caller.
void allLintProse() {}

const ordinary = '// ignore: unused_element';
const raw = r'// ignore_for_file: unused_element';
const multiline = '''
// ignore: unused_element
''';
const rawMultiline = r'''
// ignore_for_file: unused_element
''';
/* // ignore: unused_element */
// This is prose mentioning // ignore: unused_element, not a directive.

Configure prefer-commenting-analyzer-ignores

Set its severity in falcon.json. See the configuration guide.

falcon.jsonjson
{
  "linter": {
    "rules": {
      "style": {
        "prefer-commenting-analyzer-ignores": "error"
      }
    }
  }
}

Or silence one occurrence with a suppression comment; the reason is required.

example.dartdart
// falcon-ignore lint/style/prefer-commenting-analyzer-ignores: <reason>