Skip to main content

prefer-correct-handler-name

added in: 1.11.0
style
⚙️
Pro+

Warns when the callback handler name does not matched the configured one.

note

This rule does not take _ into account when checking the name.

⚙️ Config​

Set name-pattern (default is ^handle[A-Z]+) to set the expected field name.

Set ignore-functions (default is true) to exclude global function used as tear-offs (example).

Set ignore-public (default is false) to exclude public function or method invocations (example).

analysis_options.yaml
dart_code_metrics:
  rules:
    - prefer-correct-handler-name:
        name-pattern: ^handle[A-Z]+
        ignore-functions: true
        ignore-public: false

Example​

❌ Bad:

class _MyHomePageState<T> extends State<MyHomePage> {
  @override
  Widget build(BuildContext context) {
    SomeClassWithCallbacks(
      someWork, // LINT: This handler name does not match the configured pattern: ^handle[A-Z]+. Try renaming it.
      onSecond: someWork, // LINT: This handler name does not match the configured pattern: ^handle[A-Z]+. Try renaming it.
      onThird: () => someWork(), // LINT: This handler name does not match the configured pattern: ^handle[A-Z]+. Try renaming it.
      onForth: () async => await someAsyncWork(), // LINT: This handler name does not match the configured pattern: ^handle[A-Z]+. Try renaming it.
    );
  }

  void someWork() {}

  Future<void> someAsyncWork() {}

  void _handleWork() {}
}

✅ Good:

class _MyHomePageState<T> extends State<MyHomePage> {
  @override
  Widget build(BuildContext context) {
    SomeClassWithCallbacks(
      _handleWork,
      onSecond: _handleWork,
      onThird: widget.onWork,
      onForth: _handleWork,
    );
  }

  void someWork() {}

  Future<void> someAsyncWork() {}

  void _handleWork() {}
}

Example with "ignore-functions"​

Config
analysis_options.yaml
dart_code_metrics:
  rules:
    - prefer-correct-handler-name:
        ignore-functions: false

❌ Bad:

class _MyHomePageState<T> extends State<MyHomePage> {
  @override
  Widget build(BuildContext context) {
    SomeClassWithCallbacks(
      someWork, // LINT: This handler name does not match the configured pattern: ^handle[A-Z]+. Try renaming it.
    );
  }
}

void someWork() {}

Example with "ignore-public"​

Config
analysis_options.yaml
dart_code_metrics:
  rules:
    - prefer-correct-handler-name:
        ignore-public: true

✅ Good:

class _MyHomePageState<T> extends State<MyHomePage> {
  @override
  Widget build(BuildContext context) {
    SomeClassWithCallbacks(
      someWork, // Correct, public methods are ignored
    );
  }

  void someWork() {}
}