Skip to main content

banned-usage

v1.3.0
warning
effort: 6m
configurable
teams+

Warns when the configured class, method, field, constructor, or property is referenced in code.

Example: When you add some extra functionality 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 5 fields (name (or name-pattern), description, paths, exclude-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.
  • Set exclude-paths (can be a regular expression, optional) to configure the list of paths the entry will not apply to.

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
            paths:
              - .*.dart
          - 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
          - type: 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.

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();
Last updated on