Skip to main content

banned-usage

added in: 1.3.0
warning
⚙️
Pro+

Warns when the configured method, field, constructor, or property name is used.

Example: When you add some extra functionalities to built-in Flutter functions (such as logging for showDialog), you may want to ban the original Flutter function and use your own version.

note

This rule requires configuration in order to highlight any issues.

⚙️ Config​

warning

This rule also triggers on code from external packages / core libraries. To avoid this, you can pass a more specific name (for example, 'DateTime.now' instead of 'now').

Set entries (default is empty) to configure the list of entries for usages to ban.

Each entry is either an object with 4 fields (name (or name-pattern), description, paths and severity):

  • Set name to configure the identifier name (to pass a regular expression, set name-pattern instead).
  • Set name-pattern (optional) to configure a regular expression for the identifier name.
  • Set description to configure a user-facing message for each issue created from this config entry.
  • Set severity (optional) to override default severity for the given entry.
  • Set paths (optional) to configure the list of regular expressions the entry will apply to. If unset, applies to all files.

or a type entry (type and entries):

  • Set type to configure the type for which the usages should be banned.
analysis_options.yaml
dart_code_metrics:
  rules:
    - banned-usage:
        entries:
        - type: List
          entries:
            - name: sort
              description: Use "sorted" instead
            - name-pattern: '^clear'
              description: Do not use any clear method
            - name: reversed
              description: Do not reverse a list
        - name: showDialog
          description: Please use myShowDialog in this package
        - name: strangeName
          description: The name is too strange
          paths:
            - .*.dart
        - name: AnotherStrangeName
          description: Oops
        - name: StrangeClass.someMethod
          description: Please use a NonStrangeClass.someMethod instead
        - name: DateTime.now
          description: Please use a clock.now instead
          severity: error
        - name: StaticClass.field
          description: Do not use this field
        - name: MyEnum.firstValue
          description: Do not use this enum value
        - name: SomeClass
          entries:
            - name: call
              description: Do not use implicit call()
            - name: new
              description: Do not create

Example​

❌ Bad:

// suppose the configuration is the one shown above

showDialog('some_arguments', 'another_argument'); // LINT: Please use myShowDialog in this package.
material.showDialog('some_arguments', 'another_argument'); // LINT: Please use myShowDialog in this package.

var strangeName = 42; // LINT: The name is too strange.

void strangeName() {} // LINT: The name is too strange.

// LINT: Oops.
class AnotherStrangeName {
  late var strangeName; // LINT: The name is too strange.
}

StrangeClass.someMethod(); // LINT: Please use a NonStrangeClass.someMethod instead.
NonStrangeClass.someMethod();

DateTime.now(); // LINT: Please use a clock.now instead.
DateTime.now().day; // LINT: Please use a clock.now instead.
class DateTimeTest {
  final currentTimestamp = DateTime.now(); // LINT: Please use a clock.now instead.
}
DateTime currentTimestamp = DateTime('01.01.1959');

final list = [1, 2, 3];
list.sort(); // LINT: Use "sorted" instead.

✅ Good:

myShowDialog();
NonStrangeClass.someMethod();

clock.now();
clock.now().day;

class DateTimeTest {
  final currentTimestamp = clock.now();
}

final list = [1, 2, 3];
final newList = list.sorted();