Linter rules

Use the Dart linter to identify possible problems in your Dart code. You can use the linter through your IDE or with the dart analyze command. For information on how to enable and disable individual linter rules, see individual rules sections of the analyzer documentation.

This page lists all the linter rules, with details such as when you might want to use each rule, what code patterns trigger it, and how you might fix your code.

Predefined rule sets

To avoid the need to individually select compatible linter rules, consider starting with a linter rule set, which the following packages provide:

lints

Contains two rule sets curated by the Dart team. We recommend using at least the core rule set, which is used when scoring packages uploaded to pub.dev. Or, better yet, use the recommended rule set, a superset of core that identifies additional issues and enforces style and format. If you’re writing Flutter code, use the rule set in the flutter_lints package, which builds on lints.

flutter_lints

Contains the flutter rule set, which the Flutter team encourages you to use in Flutter apps, packages, and plugins. This rule set is a superset of the recommended set, which is itself a superset of the core set that partially determines the score of packages uploaded to pub.dev.

To learn how to use a specific rule set, see the documentation for enabling and disabling linter rules.

Rule types

Each rule is in one of the following groups:

Errors

Possible errors or mistakes in your code.

Style

Matters of style, largely derived from the Dart style guide.

Pub

Possible issues with pub package setup.

Maturity levels

Each rule also has a maturity level:

Stable

These rules are safe to use and are verified as functional with the latest versions of the Dart language. All rules are considered stable unless they’re marked as experimental or deprecated.

Experimental

These rules are still under evaluation and might never be stabilized. Use these with caution and report any issues you come across.

Deprecated

These rules are no longer suggested for use and might be removed in a future linter release.

Quick fixes

Some rules can be fixed automatically using quick fixes. A quick fix is an automated edit targeted at fixing the issue reported by the linter rule.

If the rule has a quick fix, it can be applied using dart fix or using your editor with Dart support. To learn more, see Quick fixes for analysis issues.

Error rules

These rules identify possible errors and other mistakes in your code.

always_use_package_imports

Avoid relative imports for files in lib/.

This rule is available as of Dart 2.10.0.

This rule has a quick fix available.

Incompatible rules: prefer_relative_imports

Details

DO avoid relative imports for files in lib/.

When mixing relative and absolute imports it’s possible to create confusion where the same member gets imported in two different ways. One way to avoid that is to ensure you consistently use absolute imports for files within the lib/ directory.

This is the opposite of ‘prefer_relative_imports’.

You can also use ‘avoid_relative_lib_imports’ to disallow relative imports of files within lib/ directory outside of it (for example test/).

BAD:

import 'baz.dart';

import 'src/bag.dart'

import '../lib/baz.dart';

...

GOOD:

import 'package:foo/bar.dart';

import 'package:foo/baz.dart';

import 'package:foo/src/baz.dart';
...

avoid_dynamic_calls

Avoid method calls or property accesses on a “dynamic” target.

This rule is available as of Dart 2.12.0.

Details

DO avoid method calls or accessing properties on an object that is either explicitly or implicitly statically typed “dynamic”. Dynamic calls are treated slightly different in every runtime environment and compiler, but most production modes (and even some development modes) have both compile size and runtime performance penalties associated with dynamic calls.

Additionally, targets typed “dynamic” disables most static analysis, meaning it is easier to lead to a runtime “NoSuchMethodError” or “NullError” than properly statically typed Dart code.

There is an exception to methods and properties that exist on “Object?”:

• a.hashCode
• a.runtimeType
• a.noSuchMethod(someInvocation)
• a.toString()

… these members are dynamically dispatched in the web-based runtimes, but not in the VM-based ones. Additionally, they are so common that it would be very punishing to disallow any.toString() or any == true, for example.

Note that despite “Function” being a type, the semantics are close to identical to “dynamic”, and calls to an object that is typed “Function” will also trigger this lint.

BAD:

void explicitDynamicType(dynamic object) {
  print(object.foo());
}

void implicitDynamicType(object) {
  print(object.foo());
}

abstract class SomeWrapper {
  T doSomething<T>();
}

void inferredDynamicType(SomeWrapper wrapper) {
  var object = wrapper.doSomething();
  print(object.foo());
}

void callDynamic(dynamic function) {
  function();
}

void functionType(Function function) {
  function();
}

GOOD:

void explicitType(Fooable object) {
  object.foo();
}

void castedType(dynamic object) {
  (object as Fooable).foo();
}

abstract class SomeWrapper {
  T doSomething<T>();
}

void inferredType(SomeWrapper wrapper) {
  var object = wrapper.doSomething<Fooable>();
  object.foo();
}

void functionTypeWithParameters(Function() function) {
  function();
}

avoid_empty_else

Avoid empty else statements.

This rule is available as of Dart 2.0.0.

Rule sets: core, recommended, flutter

This rule has a quick fix available.

Details

AVOID empty else statements.

BAD:

if (x > y)
  print("1");
else ;
  print("2");

avoid_print

Avoid print calls in production code.

This rule is available as of Dart 2.5.0.

Rule sets: flutter

This rule has a quick fix available.

Details

DO avoid print calls in production code.

For production code, consider using a logging framework. If you are using Flutter, you can use debugPrint or surround print calls with a check for kDebugMode

BAD:

void f(int x) {
  print('debug: $x');
  ...
}

GOOD:

void f(int x) {
  debugPrint('debug: $x');
  ...
}

GOOD:

void f(int x) {
  log('log: $x');
  ...
}

GOOD:

void f(int x) {
  if (kDebugMode) {
      print('debug: $x');
  }
  ...
}

avoid_relative_lib_imports

Avoid relative imports for files in lib/.

This rule is available as of Dart 2.0.0.

Rule sets: core, recommended, flutter

This rule has a quick fix available.

Details

DO avoid relative imports for files in lib/.

When mixing relative and absolute imports it’s possible to create confusion where the same member gets imported in two different ways. An easy way to avoid that is to ensure you have no relative imports that include lib/ in their paths.

You can also use ‘always_use_package_imports’ to disallow relative imports between files within lib/.

BAD:

import 'package:foo/bar.dart';

import '../lib/baz.dart';

...

GOOD:

import 'package:foo/bar.dart';

import 'baz.dart';

...

avoid_returning_null_for_future

Avoid returning null for Future.

This rule is currently deprecated and available as of Dart 2.1.1.

This rule has a quick fix available.

Details

AVOID returning null for Future.

It is almost always wrong to return null for a Future. Most of the time the developer simply forgot to put an async keyword on the function.

avoid_slow_async_io

Avoid slow async dart:io methods.

This rule is available as of Dart 2.0.0.

Details

AVOID using the following asynchronous file I/O methods because they are much slower than their synchronous counterparts.

• Directory.exists
• Directory.stat
• File.lastModified
• File.exists
• File.stat
• FileSystemEntity.isDirectory
• FileSystemEntity.isFile
• FileSystemEntity.isLink
• FileSystemEntity.type

BAD:

import 'dart:io';

Future<Null> someFunction() async {
  var file = File('/path/to/my/file');
  var now = DateTime.now();
  if ((await file.lastModified()).isBefore(now)) print('before'); // LINT
}

GOOD:

import 'dart:io';

Future<Null> someFunction() async {
  var file = File('/path/to/my/file');
  var now = DateTime.now();
  if (file.lastModifiedSync().isBefore(now)) print('before'); // OK
}

avoid_type_to_string

Avoid .toString() in production code since results may be minified.

This rule is available as of Dart 2.12.0.

Details

DO avoid calls to .toString() in production code, since it does not contractually return the user-defined name of the Type (or underlying class). Development-mode compilers where code size is not a concern use the full name, but release-mode compilers often choose to minify these symbols.

BAD:

void bar(Object other) {
  if (other.runtimeType.toString() == 'Bar') {
    doThing();
  }
}

Object baz(Thing myThing) {
  return getThingFromDatabase(key: myThing.runtimeType.toString());
}

GOOD:

void bar(Object other) {
  if (other is Bar) {
    doThing();
  }
}

class Thing {
  String get thingTypeKey => ...
}

Object baz(Thing myThing) {
  return getThingFromDatabase(key: myThing.thingTypeKey);
}

avoid_types_as_parameter_names

Avoid types as parameter names.

This rule is available as of Dart 2.0.0.

Rule sets: core, recommended, flutter

This rule has a quick fix available.

Details

AVOID using a parameter name that is the same as an existing type.

BAD:

m(f(int));

GOOD:

m(f(int v));

avoid_web_libraries_in_flutter

Avoid using web-only libraries outside Flutter web plugin packages.

This rule is available as of Dart 2.6.0.

Rule sets: flutter

Details

AVOID using web libraries, dart:html, dart:js and dart:js_util in Flutter packages that are not web plugins. These libraries are not supported outside a web context; functionality that depends on them will fail at runtime in Flutter mobile, and their use is generally discouraged in Flutter web.

Web library access is allowed in:

• plugin packages that declare web as a supported context

otherwise, imports of dart:html, dart:js and dart:js_util are disallowed.

cancel_subscriptions

Cancel instances of dart.async.StreamSubscription.

This rule is available as of Dart 2.0.0.

Details

DO invoke cancel on instances of dart.async.StreamSubscription.

Cancelling instances of StreamSubscription prevents memory leaks and unexpected behavior.

BAD:

class A {
  StreamSubscription _subscriptionA; // LINT
  void init(Stream stream) {
    _subscriptionA = stream.listen((_) {});
  }
}

BAD:

void someFunction() {
  StreamSubscription _subscriptionF; // LINT
}

GOOD:

class B {
  StreamSubscription _subscriptionB; // OK
  void init(Stream stream) {
    _subscriptionB = stream.listen((_) {});
  }

  void dispose(filename) {
    _subscriptionB.cancel();
  }
}

GOOD:

void someFunctionOK() {
  StreamSubscription _subscriptionB; // OK
  _subscriptionB.cancel();
}

close_sinks

Close instances of dart.core.Sink.

This rule is available as of Dart 2.0.0.

Details

DO invoke close on instances of dart.core.Sink.

Closing instances of Sink prevents memory leaks and unexpected behavior.

BAD:

class A {
  IOSink _sinkA;
  void init(filename) {
    _sinkA = File(filename).openWrite(); // LINT
  }
}

BAD:

void someFunction() {
  IOSink _sinkF; // LINT
}

GOOD:

class B {
  IOSink _sinkB;
  void init(filename) {
    _sinkB = File(filename).openWrite(); // OK
  }

  void dispose(filename) {
    _sinkB.close();
  }
}

GOOD:

void someFunctionOK() {
  IOSink _sinkFOK; // OK
  _sinkFOK.close();
}

collection_methods_unrelated_type

Invocation of various collection methods with arguments of unrelated types.

This rule is available as of Dart 2.19.0.

Details

DON’T invoke certain collection method with an argument with an unrelated type.

Doing this will invoke == on the collection’s elements and most likely will return false.

An argument passed to a collection method should relate to the collection type as follows:

• an argument to Iterable<E>.contains should be related to E
• an argument to List<E>.remove should be related to E
• an argument to Map<K, V>.containsKey should be related to K
• an argument to Map<K, V>.containsValue should be related to V
• an argument to Map<K, V>.remove should be related to K
• an argument to Map<K, V>.[] should be related to K
• an argument to Queue<E>.remove should be related to E
• an argument to Set<E>.lookup should be related to E
• an argument to Set<E>.remove should be related to E

BAD:

void someFunction() {
  var list = <int>[];
  if (list.contains('1')) print('someFunction'); // LINT
}

BAD:

void someFunction() {
  var set = <int>{};
  set.remove('1'); // LINT
}

GOOD:

void someFunction() {
  var list = <int>[];
  if (list.contains(1)) print('someFunction'); // OK
}

GOOD:

void someFunction() {
  var set = <int>{};
  set.remove(1); // OK
}

comment_references

Only reference in scope identifiers in doc comments.

This rule is available as of Dart 2.0.0.

Details

DO reference only in scope identifiers in doc comments.

If you surround things like variable, method, or type names in square brackets, then dart doc will look up the name and link to its docs. For this all to work, ensure that all identifiers in docs wrapped in brackets are in scope.

For example, assuming outOfScopeId is out of scope:

BAD:

/// Return true if [value] is larger than [outOfScopeId].
bool isOutOfRange(int value) { ... }

GOOD:

/// Return the larger of [a] or [b].
int max_int(int a, int b) { ... }

Note that the square bracket comment format is designed to allow comments to refer to declarations using a fairly natural format but does not allow arbitrary expressions. In particular, code references within square brackets can consist of either

• a single identifier where the identifier is any identifier in scope for the comment (see the spec for what is in scope in doc comments),
• two identifiers separated by a period where the first identifier is the name of a class that is in scope and the second is the name of a member declared in the class,
• a single identifier followed by a pair of parentheses where the identifier is the name of a class that is in scope (used to refer to the unnamed constructor for the class), or
• two identifiers separated by a period and followed by a pair of parentheses where the first identifier is the name of a class that is in scope and the second is the name of a named constructor (not strictly necessary, but allowed for consistency).

control_flow_in_finally

Avoid control flow in finally blocks.

This rule is available as of Dart 2.0.0.

Rule sets: recommended, flutter

Details

AVOID control flow leaving finally blocks.

Using control flow in finally blocks will inevitably cause unexpected behavior that is hard to debug.

BAD:

class BadReturn {
  double nonCompliantMethod() {
    try {
      return 1 / 0;
    } catch (e) {
      print(e);
    } finally {
      return 1.0; // LINT
    }
  }
}

BAD:

class BadContinue {
  double nonCompliantMethod() {
    for (var o in [1, 2]) {
      try {
        print(o / 0);
      } catch (e) {
        print(e);
      } finally {
        continue; // LINT
      }
    }
    return 1.0;
  }
}

BAD:

class BadBreak {
  double nonCompliantMethod() {
    for (var o in [1, 2]) {
      try {
        print(o / 0);
      } catch (e) {
        print(e);
      } finally {
        break; // LINT
      }
    }
    return 1.0;
  }
}

GOOD:

class Ok {
  double compliantMethod() {
    var i = 5;
    try {
      i = 1 / 0;
    } catch (e) {
      print(e); // OK
    }
    return i;
  }
}

deprecated_member_use_from_same_package

Avoid using deprecated elements from within the package in which they are declared.

This rule is available as of Dart 3.0.0.

Details

Elements which are annotated with @deprecated should not be referenced from within the package in which they are declared.

AVOID using deprecated elements.

…

BAD:

// Declared in one library:
class Foo {
  @Deprecated("Use 'm2' instead")
  void m1() {}

  void m2({
      @Deprecated('This is an old parameter') int? p,
  })
}

@Deprecated('Do not use')
int x = 0;

// In the same or another library, but within the same package:
void m(Foo foo) {
  foo.m1();
  foo.m2(p: 7);
  x = 1;
}

Deprecated elements can be used from within other deprecated elements, in order to allow for the deprecation of a collection of APIs together as one unit.

GOOD:

// Declared in one library:
class Foo {
  @Deprecated("Use 'm2' instead")
  void m1() {}

  void m2({
      @Deprecated('This is an old parameter') int? p,
  })
}

@Deprecated('Do not use')
int x = 0;

// In the same or another library, but within the same package:
@Deprecated('Do not use')
void m(Foo foo) {
  foo.m1();
  foo.m2(p: 7);
  x = 1;
}

diagnostic_describe_all_properties

DO reference all public properties in debug methods.

This rule is available as of Dart 2.3.0.

This rule has a quick fix available.

Details

DO reference all public properties in debug method implementations.

Implementers of Diagnosticable should reference all public properties in a debugFillProperties(...) or debugDescribeChildren(...) method implementation to improve debuggability at runtime.

Public properties are defined as fields and getters that are

• not package-private (e.g., prefixed with _)
• not static or overriding
• not themselves Widgets or collections of Widgets

In addition, the “debug” prefix is treated specially for properties in Flutter. For the purposes of diagnostics, a property foo and a prefixed property debugFoo are treated as effectively describing the same property and it is sufficient to refer to one or the other.

BAD:

class Absorber extends Widget {
  bool get absorbing => _absorbing;
  bool _absorbing;
  bool get ignoringSemantics => _ignoringSemantics;
  bool _ignoringSemantics;
  @override
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
    properties.add(DiagnosticsProperty<bool>('absorbing', absorbing));
    // Missing reference to ignoringSemantics
  }
}

GOOD:

class Absorber extends Widget {
  bool get absorbing => _absorbing;
  bool _absorbing;
  bool get ignoringSemantics => _ignoringSemantics;
  bool _ignoringSemantics;
  @override
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
    properties.add(DiagnosticsProperty<bool>('absorbing', absorbing));
    properties.add(DiagnosticsProperty<bool>('ignoringSemantics', ignoringSemantics));
  }
}

discarded_futures

Don’t invoke asynchronous functions in non-async blocks.

This rule is available as of Dart 2.18.0.

This rule has a quick fix available.

Details

Making asynchronous calls in non-async functions is usually the sign of a programming error. In general these functions should be marked async and such futures should likely be awaited (as enforced by unawaited_futures).

DON’T invoke asynchronous functions in non-async blocks.

BAD:

void recreateDir(String path) {
  deleteDir(path);
  createDir(path);
}

Future<void> deleteDir(String path) async {}

Future<void> createDir(String path) async {}

GOOD:

Future<void> recreateDir(String path) async {
  await deleteDir(path);
  await createDir(path);
}

Future<void> deleteDir(String path) async {}

Future<void> createDir(String path) async {}

empty_statements

Avoid empty statements.

This rule is available as of Dart 2.0.0.

Rule sets: recommended, flutter

This rule has a quick fix available.

Details

AVOID empty statements.

Empty statements almost always indicate a bug.

For example,

BAD:

if (complicated.expression.foo());
  bar();

Formatted with dart format the bug becomes obvious:

if (complicated.expression.foo()) ;
bar();

Better to avoid the empty statement altogether.

GOOD:

if (complicated.expression.foo())
  bar();

hash_and_equals

Always override hashCode if overriding ==.

This rule is available as of Dart 2.0.0.

Rule sets: core, recommended, flutter

This rule has a quick fix available.

Details

DO override hashCode if overriding == and prefer overriding == if overriding hashCode.

Every object in Dart has a hashCode. Both the == operator and the hashCode property of objects must be consistent in order for a common hash map implementation to function properly. Thus, when overriding ==, the hashCode should also be overridden to maintain consistency. Similarly, if hashCode is overridden, == should be also.

BAD:

class Bad {
  final int value;
  Bad(this.value);

  @override
  bool operator ==(Object other) => other is Bad && other.value == value;
}

GOOD:

class Better {
  final int value;
  Better(this.value);

  @override
  bool operator ==(Object other) =>
      other is Better &&
      other.runtimeType == runtimeType &&
      other.value == value;

  @override
  int get hashCode => value.hashCode;
}

implicit_reopen

Don’t implicitly reopen classes.

This rule is currently experimental and available as of Dart 3.0.0.

This rule has a quick fix available.

Details

Using an interface, base, final, or sealed modifier on a class, or a base modifier on a mixin, authors can control whether classes and mixins allow being implemented, extended, and/or mixed in from outside of the library where they’re defined. In some cases, it’s possible for an author to inadvertently relax these controls and implicitly “reopen” a class. (A similar reopening cannot occur with a mixin.)

This lint guards against unintentionally reopening a class by requiring such cases to be made explicit with the @reopen annotation in package:meta.

BAD:

interface class I {}

class C extends I {} // LINT

GOOD:

interface class I {}

final class C extends I {}

interface class I {}

final class C extends I {}

import 'package:meta/meta.dart';

interface class I {}

@reopen
class C extends I {}

invalid_case_patterns

Use case expressions that are valid in Dart 3.0.

This rule is currently experimental and available as of Dart 3.0.0.

This rule has a quick fix available.

Details

Some case expressions that are valid in Dart 2.19 and below will become an error or have changed semantics when a library is upgraded to 3.0. This lint flags those expressions in order to ease migration to Dart 3.0.

Some valid switch cases in 2.19 will become compile errors in Dart 3.0:

• Set literals
• Parenthesized expressions
• Calls to identical().
• Unary operator expressions !, -, or ~ (except for - before an integer literal, which is a valid pattern and is fine)
• Binary operator expressions !=, ==, &, |, ^, ~/, >>, >>>, <<, +, -, *, /, %, <, <=, >, >=, ??.
• Conditional operator ?:
• .length calls on strings
• is and is! expressions

Examples of all of them:

switch (obj) {
  case {1}: // Set literal.
  case (1): // Parenthesized expression.
  case identical(1, 2): // `identical()` call.
  case -pi: // Unary operator.
  case 1 + 2: // Binary operator.
  case true ? 1 : 2: // Conditional operator.
  case 'hi'.length: // .length call.
  case i is int: // is expression.
}

Some valid switch cases in 2.19 are also syntactically valid patterns, but the pattern matching behavior may be different from the current constant equality behavior. They are:

List and map literals. A list or map literal can appear as a constant in a case:

switch (obj) {
  case [1, 2]: ...
  case {'k': 'v'}: ...
}

Currently, the case will only match if the incoming value has the same identity as the constant. So:

test(List<int> list) {
  switch (list) {
    case [1, 2]: print('Matched'); break;
    default: print('Did not match'); break;
  }
}

main() {
  test(const [1, 2]); // Prints "Matched".
  test([1, 2]); // Prints "Did not match".
}

With patterns, a list or map literal becomes a list or map pattern. The pattern destructures the incoming object and matches if the subpatterns all match. In other words, list and map pattern match using something more like deep equality.

With Dart 3.0, the above program prints “Matched” twice.

Constant constructor calls. Similar to collections, you can construct a constant instance of a class in a case:

class Point {
  final int x;
  final int y;
  const Point({this.x, this.y});
}

test(Point p) {
  switch (p) {
    case Point(x: 1, y: 2): print('Matched'); break;
    default: print('Did not match'); break;
  }
}

main() {
  test(const Point(1, 2)); // Prints "Matched".
  test(Point(1, 2)); // Prints "Did not match".
}

Again, like collections, the case currently only matches if the incoming value has the same identity. With patterns, the Point(...) syntax becomes an object pattern that destructures the incoming point, calls the x and y getters on it and then matches the results of those against the corresponding subpatterns.

In this example, it will print “Matched” twice.

Note that object patterns only support named fields. So any constant constructor in a case today that has positional arguments will become a compile-time error when parsed as a pattern. A constant constructor call with no arguments is a valid object pattern and only does a type test:

class Thing {
  const Thing();
}

test(Thing t) {
  switch (t) {
    case Thing(): print('Matched'); break;
    default: print('Did not match'); break;
  }
}

main() {
  test(const Thing()); // Prints "Matched".
  test(Thing()); // Prints "Did not match".
}

When interpreted as a pattern, this prints “Matched” twice.

Wildcards. Today, you can have a constant named _:

test(int n) {
  const _ = 3;
  switch (n) {
    case _: print('Matched'); break;
    default: print('Did not match'); break;
  }
}

main() {
  test(3); // Prints "Matched".
  test(5); // Prints "Did not match".
}

With patterns, the identifier _ is treated as a pattern that matches all values, so this prints “Matched” twice.

Logic operators. The logic operators && and || are valid constant expressions and also valid patterns. As a constant expression, they simply evaluate the expression to a boolean and match if the incoming value is equal to that boolean value. So:

test(bool b) {
  switch (b) {
    case true && false: print('Matched'); break;
    default: print('Did not match'); break;
  }
}

main() {
  test(false); // Prints "Matched".
  test(true); // Prints "Did not match".
}

With Dart 3.0, these become patterns. The above example prints “Did not match” twice because no boolean value can be both true and false.

Many of invalid cases can be mechanically changed to something that is valid both in Dart today and valid and means the same in Dart 3.0.

Parenthesized expressions: Provided the inner expression is one that’s not broken in Dart 3.0, just discard the parentheses.

List literals, map literals, set literals, and constant constructor calls: Put const before the literal or call. This turns it into a constant pattern which preserves the current behavior:

BAD:

case [1, 2]:
case {'k': 'v'}:
case {1, 2}:
case Point(1, 2):

GOOD:

case const [1, 2]:
case const {'k': 'v'}:
case const {1, 2}:
case const Point(1, 2):

• Wildcards: Rename the constant from _ to something else. Since the name is private, this can be done locally in the library without affecting other code.

• Everything else: For any other invalid expression, you have to hoist the expression out into a new named constant. For example, if you have code like this:

BAD:

switch (n) {
  case 1 + 2: ...
}

It can be fixed by changing it to:

GOOD:

const three = 1 + 2;

switch (n) {
  case three: ...
}

invariant_booleans

Conditions should not unconditionally evaluate to true or to false.

This rule has been removed as of the latest Dart releases.

Details

DON’T test for conditions that can be inferred at compile time or test the same condition twice.

Conditional statements using a condition which cannot be anything but false have the effect of making blocks of code non-functional. If the condition cannot evaluate to anything but true, the conditional statement is completely redundant, and makes the code less readable. It is quite likely that the code does not match the programmer’s intent. Either the condition should be removed or it should be updated so that it does not always evaluate to true or false and does not perform redundant tests. This rule will hint to the test conflicting with the linted one.

BAD:

// foo can't be both equal and not equal to bar in the same expression
if(foo == bar && something && foo != bar) {...}

BAD:

void compute(int foo) {
  if (foo == 4) {
    doSomething();
    // we know foo is equal to 4 at this point, so the next condition is always false
    if (foo > 4) {...}
    ...
  }
  ...
}

BAD:

void compute(bool foo) {
  if (foo) {
    return;
  }
  doSomething();
  // foo is always false here
  if (foo){...}
  ...
}

GOOD:

void nestedOK() {
  if (foo == bar) {
    foo = baz;
    if (foo != bar) {...}
  }
}

GOOD:

void nestedOk2() {
  if (foo == bar) {
    return;
  }

  foo = baz;
  if (foo == bar) {...} // OK
}

GOOD:

void nestedOk5() {
  if (foo != null) {
    if (bar != null) {
      return;
    }
  }

  if (bar != null) {...} // OK
}

iterable_contains_unrelated_type

Invocation of Iterable.contains with references of unrelated types.

This rule is available as of Dart 2.0.0.

Rule sets: core, recommended, flutter

Details

DON’T invoke contains on Iterable with an instance of different type than the parameter type.

Doing this will invoke == on its elements and most likely will return false.

BAD:

void someFunction() {
  var list = <int>[];
  if (list.contains('1')) print('someFunction'); // LINT
}

BAD:

void someFunction3() {
  List<int> list = <int>[];
  if (list.contains('1')) print('someFunction3'); // LINT
}

BAD:

void someFunction8() {
  List<DerivedClass2> list = <DerivedClass2>[];
  DerivedClass3 instance;
  if (list.contains(instance)) print('someFunction8'); // LINT
}

BAD:

abstract class SomeIterable<E> implements Iterable<E> {}

abstract class MyClass implements SomeIterable<int> {
  bool badMethod(String thing) => this.contains(thing); // LINT
}

GOOD:

void someFunction10() {
  var list = [];
  if (list.contains(1)) print('someFunction10'); // OK
}

GOOD:

void someFunction1() {
  var list = <int>[];
  if (list.contains(1)) print('someFunction1'); // OK
}

GOOD:

void someFunction4() {
  List<int> list = <int>[];
  if (list.contains(1)) print('someFunction4'); // OK
}

GOOD:

void someFunction5() {
  List<ClassBase> list = <ClassBase>[];
  DerivedClass1 instance;
  if (list.contains(instance)) print('someFunction5'); // OK
}

abstract class ClassBase {}

class DerivedClass1 extends ClassBase {}

GOOD:

void someFunction6() {
  List<Mixin> list = <Mixin>[];
  DerivedClass2 instance;
  if (list.contains(instance)) print('someFunction6'); // OK
}

abstract class ClassBase {}

abstract class Mixin {}

class DerivedClass2 extends ClassBase with Mixin {}

GOOD:

void someFunction7() {
  List<Mixin> list = <Mixin>[];
  DerivedClass3 instance;
  if (list.contains(instance)) print('someFunction7'); // OK
}

abstract class ClassBase {}

abstract class Mixin {}

class DerivedClass3 extends ClassBase implements Mixin {}

list_remove_unrelated_type

Invocation of remove with references of unrelated types.

This rule is available as of Dart 2.0.0.

Rule sets: core, recommended, flutter

Details

DON’T invoke remove on List with an instance of different type than the parameter type.

Doing this will invoke == on its elements and most likely will return false.

BAD:

void someFunction() {
  var list = <int>[];
  if (list.remove('1')) print('someFunction'); // LINT
}

BAD:

void someFunction3() {
  List<int> list = <int>[];
  if (list.remove('1')) print('someFunction3'); // LINT
}

BAD:

void someFunction8() {
  List<DerivedClass2> list = <DerivedClass2>[];
  DerivedClass3 instance;
  if (list.remove(instance)) print('someFunction8'); // LINT
}

BAD:

abstract class SomeList<E> implements List<E> {}

abstract class MyClass implements SomeList<int> {
  bool badMethod(String thing) => this.remove(thing); // LINT
}

GOOD:

void someFunction10() {
  var list = [];
  if (list.remove(1)) print('someFunction10'); // OK
}

GOOD:

void someFunction1() {
  var list = <int>[];
  if (list.remove(1)) print('someFunction1'); // OK
}

GOOD:

void someFunction4() {
  List<int> list = <int>[];
  if (list.remove(1)) print('someFunction4'); // OK
}

GOOD:

void someFunction5() {
  List<ClassBase> list = <ClassBase>[];
  DerivedClass1 instance;
  if (list.remove(instance)) print('someFunction5'); // OK
}

abstract class ClassBase {}

class DerivedClass1 extends ClassBase {}

GOOD:

void someFunction6() {
  List<Mixin> list = <Mixin>[];
  DerivedClass2 instance;
  if (list.remove(instance)) print('someFunction6'); // OK
}

abstract class ClassBase {}

abstract class Mixin {}

class DerivedClass2 extends ClassBase with Mixin {}

GOOD:

void someFunction7() {
  List<Mixin> list = <Mixin>[];
  DerivedClass3 instance;
  if (list.remove(instance)) print('someFunction7'); // OK
}

abstract class ClassBase {}

abstract class Mixin {}

class DerivedClass3 extends ClassBase implements Mixin {}

literal_only_boolean_expressions

Boolean expression composed only with literals.

This rule is available as of Dart 2.0.0.

Details

DON’T test for conditions composed only by literals, since the value can be inferred at compile time.

Conditional statements using a condition which cannot be anything but FALSE have the effect of making blocks of code non-functional. If the condition cannot evaluate to anything but true, the conditional statement is completely redundant, and makes the code less readable. It is quite likely that the code does not match the programmer’s intent. Either the condition should be removed or it should be updated so that it does not always evaluate to true or false.

BAD:

void bad() {
  if (true) {} // LINT
}

BAD:

void bad() {
  if (true && 1 != 0) {} // LINT
}

BAD:

void bad() {
  if (1 != 0 && true) {} // LINT
}

BAD:

void bad() {
  if (1 < 0 && true) {} // LINT
}

BAD:

void bad() {
  if (true && false) {} // LINT
}

BAD:

void bad() {
  if (1 != 0) {} // LINT
}

BAD:

void bad() {
  if (true && 1 != 0 || 3 < 4) {} // LINT
}

BAD:

void bad() {
  if (1 != 0 || 3 < 4 && true) {} // LINT
}

NOTE: that an exception is made for the common while (true) { } idiom, which is often reasonably preferred to the equivalent for (;;).

GOOD:

void good() {
  while (true) {
    // Do stuff.
  }
}

no_adjacent_strings_in_list

Don’t use adjacent strings in list.

This rule is available as of Dart 2.0.0.

Details

DON’T use adjacent strings in a list.

This can indicate a forgotten comma.

BAD:

List<String> list = <String>[
  'a'
  'b',
  'c',
];

GOOD:

List<String> list = <String>[
  'a' +
  'b',
  'c',
];

no_duplicate_case_values

Don’t use more than one case with same value.

This rule is available as of Dart 2.0.0.

Rule sets: core, recommended, flutter

This rule has a quick fix available.

Details

DON’T use more than one case with same value.

This is usually a typo or changed value of constant.

BAD:

const int A = 1;
switch (v) {
  case 1:
  case 2:
  case A:
  case 2:
}

GOOD:

const int A = 1;
switch (v) {
  case A:
  case 2:
}

NOTE: this lint only reports duplicate cases in libraries opted in to Dart 2.19 and below. In Dart 3.0 and after, duplicate cases are reported as dead code by the analyzer.

no_logic_in_create_state

Don’t put any logic in createState.

This rule is available as of Dart 2.8.1.

Rule sets: flutter

Details

DON’T put any logic in createState().

Implementations of createState() should return a new instance of a State object and do nothing more. Since state access is preferred via the widget field, passing data to State objects using custom constructor parameters should also be avoided and so further, the State constructor is required to be passed no arguments.

BAD:

MyState global;

class MyStateful extends StatefulWidget {
  @override
  MyState createState() {
    global = MyState();
    return global;
  } 
}

class MyStateful extends StatefulWidget {
  @override
  MyState createState() => MyState()..field = 42;
}

class MyStateful extends StatefulWidget {
  @override
  MyState createState() => MyState(42);
}

GOOD:

class MyStateful extends StatefulWidget {
  @override
  MyState createState() {
    return MyState();
  }
}

prefer_relative_imports

Prefer relative imports for files in lib/.

This rule is available as of Dart 2.6.0.

This rule has a quick fix available.

Incompatible rules: always_use_package_imports

Details

PREFER relative imports for files in lib/.

When mixing relative and absolute imports it’s possible to create confusion where the same member gets imported in two different ways. One way to avoid that is to ensure you consistently use relative imports for files within the lib/ directory.

BAD:

import 'package:my_package/bar.dart';

GOOD:

import 'bar.dart';

prefer_void_to_null

Don’t use the Null type, unless you are positive that you don’t want void.

This rule is available as of Dart 2.1.0.

Rule sets: recommended, flutter

This rule has a quick fix available.

Details

DON’T use the type Null where void would work.

BAD:

Null f() {}
Future<Null> f() {}
Stream<Null> f() {}
f(Null x) {}

GOOD:

void f() {}
Future<void> f() {}
Stream<void> f() {}
f(void x) {}

Some exceptions include formulating special function types:

Null Function(Null, Null);

and for making empty literals which are safe to pass into read-only locations for any type of map or list:

<Null>[];
<int, Null>{};

test_types_in_equals

Test type arguments in operator ==(Object other).

This rule is available as of Dart 2.0.0.

Details

DO test type arguments in operator ==(Object other).

Not testing types might result in null pointer exceptions which will be unexpected for consumers of your class.

BAD:

class Field {
}

class Bad {
  final Field someField;

  Bad(this.someField);

  @override
  bool operator ==(Object other) {
    Bad otherBad = other as Bad; // LINT
    bool areEqual = otherBad != null && otherBad.someField == someField;
    return areEqual;
  }

  @override
  int get hashCode {
    return someField.hashCode;
  }
}

GOOD:

class Field {
}

class Good {
  final Field someField;

  Good(this.someField);

  @override
  bool operator ==(Object other) {
    if (identical(this, other)) {
      return true;
    }
    return other is Good &&
        this.someField == other.someField;
  }

  @override
  int get hashCode {
    return someField.hashCode;
  }
}

throw_in_finally

Avoid throw in finally block.

This rule is available as of Dart 2.0.0.

Details

AVOID throwing exceptions in finally blocks.

Throwing exceptions in finally blocks will inevitably cause unexpected behavior that is hard to debug.

BAD:

class BadThrow {
  double nonCompliantMethod() {
    try {
      print('hello world! ${1 / 0}');
    } catch (e) {
      print(e);
    } finally {
      throw 'Find the hidden error :P'; // LINT
    }
  }
}

GOOD:

class Ok {
  double compliantMethod() {
    var i = 5;
    try {
      i = 1 / 0;
    } catch (e) {
      print(e); // OK
    }
    return i;
  }
}

unnecessary_statements

Avoid using unnecessary statements.

This rule is available as of Dart 2.0.0.

Details

AVOID using unnecessary statements.

Statements which have no clear effect are usually unnecessary, or should be broken up.

For example,

BAD:

myvar;
list.clear;
1 + 2;
methodOne() + methodTwo();
foo ? bar : baz;

Though the added methods have a clear effect, the addition itself does not unless there is some magical overload of the + operator.

Usually code like this indicates an incomplete thought, and is a bug.

GOOD:

some.method();
const SomeClass();
methodOne();
methodTwo();
foo ? bar() : baz();
return myvar;

unrelated_type_equality_checks

Equality operator == invocation with references of unrelated types.

This rule is available as of Dart 2.0.0.

Rule sets: core, recommended, flutter

Details

DON’T Compare references of unrelated types for equality.

Comparing references of a type where neither is a subtype of the other most likely will return false and might not reflect programmer’s intent.

Int64 and Int32 from package:fixnum allow comparing to int provided the int is on the right hand side. The lint allows this as a special case.

BAD:

void someFunction() {
  var x = '1';
  if (x == 1) print('someFunction'); // LINT
}

BAD:

void someFunction1() {
  String x = '1';
  if (x == 1) print('someFunction1'); // LINT
}

BAD:

void someFunction13(DerivedClass2 instance) {
  var other = DerivedClass3();

  if (other == instance) print('someFunction13'); // LINT
}

class ClassBase {}

class DerivedClass1 extends ClassBase {}

abstract class Mixin {}

class DerivedClass2 extends ClassBase with Mixin {}

class DerivedClass3 extends ClassBase implements Mixin {}

GOOD:

void someFunction2() {
  var x = '1';
  var y = '2';
  if (x == y) print(someFunction2); // OK
}

GOOD:

void someFunction3() {
  for (var i = 0; i < 10; i++) {
    if (i == 0) print(someFunction3); // OK
  }
}

GOOD:

void someFunction4() {
  var x = '1';
  if (x == null) print(someFunction4); // OK
}

GOOD:

void someFunction7() {
  List someList;

  if (someList.length == 0) print('someFunction7'); // OK
}

GOOD:

void someFunction8(ClassBase instance) {
  DerivedClass1 other;

  if (other == instance) print('someFunction8'); // OK
}

GOOD:

void someFunction10(unknown) {
  var what = unknown - 1;
  for (var index = 0; index < unknown; index++) {
    if (what == index) print('someFunction10'); // OK
  }
}

GOOD:

void someFunction11(Mixin instance) {
  var other = DerivedClass2();

  if (other == instance) print('someFunction11'); // OK
  if (other != instance) print('!someFunction11'); // OK
}

class ClassBase {}

abstract class Mixin {}

class DerivedClass2 extends ClassBase with Mixin {}

unsafe_html

Avoid unsafe HTML APIs.

This rule is available as of Dart 2.4.0.

Details

AVOID

• assigning directly to the href field of an AnchorElement
• assigning directly to the src field of an EmbedElement, IFrameElement, or ScriptElement
• assigning directly to the srcdoc field of an IFrameElement
• calling the createFragment method of Element
• calling the open method of Window
• calling the setInnerHtml method of Element
• calling the Element.html constructor
• calling the DocumentFragment.html constructor

BAD:

var script = ScriptElement()..src = 'foo.js';

use_build_context_synchronously

Do not use BuildContexts across async gaps.

This rule is currently experimental and available as of Dart 2.13.0.

Rule sets: flutter

Details

DON’T use BuildContext across asynchronous gaps.

Storing BuildContext for later usage can easily lead to difficult to diagnose crashes. Asynchronous gaps are implicitly storing BuildContext and are some of the easiest to overlook when writing code.

When a BuildContext is used, its mounted property must be checked after an asynchronous gap.

BAD:

void onButtonTapped(BuildContext context) async {
  await Future.delayed(const Duration(seconds: 1));
  Navigator.of(context).pop();
}

GOOD:

void onButtonTapped(BuildContext context) {
  Navigator.of(context).pop();
}

GOOD:

void onButtonTapped() async {
  await Future.delayed(const Duration(seconds: 1));

  if (!context.mounted) return;
  Navigator.of(context).pop();
}

use_key_in_widget_constructors

Use key in widget constructors.

This rule is available as of Dart 2.8.1.

Rule sets: flutter

This rule has a quick fix available.

Details

DO use key in widget constructors.

It’s a good practice to expose the ability to provide a key when creating public widgets.

BAD:

class MyPublicWidget extends StatelessWidget {
}

GOOD:

class MyPublicWidget extends StatelessWidget {
  MyPublicWidget({super.key});
}

valid_regexps

Use valid regular expression syntax.

This rule is available as of Dart 2.0.0.

Rule sets: core, recommended, flutter

Details

DO use valid regular expression syntax when creating regular expression instances.

Regular expressions created with invalid syntax will throw a FormatException at runtime so should be avoided.

BAD:

print(RegExp(r'(').hasMatch('foo()'));

GOOD:

print(RegExp(r'\(').hasMatch('foo()'));

Style rules

These rules identify opportunities for style improvements, largely derived from the Dart style guide.

always_declare_return_types

Declare method return types.

This rule is available as of Dart 2.0.0.

This rule has a quick fix available.

Details

DO declare method return types.

When declaring a method or function always specify a return type. Declaring return types for functions helps improve your codebase by allowing the analyzer to more adequately check your code for errors that could occur during runtime.

BAD:

main() { }

_bar() => _Foo();

class _Foo {
  _foo() => 42;
}

GOOD:

void main() { }

_Foo _bar() => _Foo();

class _Foo {
  int _foo() => 42;
}

typedef predicate = bool Function(Object o);

always_put_control_body_on_new_line

Separate the control structure expression from its statement.

This rule is available as of Dart 2.0.0.

This rule has a quick fix available.

Details

From the style guide for the flutter repo:

DO separate the control structure expression from its statement.

Don’t put the statement part of an if, for, while, do on the same line as the expression, even if it is short. Doing so makes it unclear that there is relevant code there. This is especially important for early returns.

BAD:

if (notReady) return;

if (notReady)
  return;
else print('ok')

while (condition) i += 1;

GOOD:

if (notReady)
  return;

if (notReady)
  return;
else
  print('ok')

while (condition)
  i += 1;

Note that this rule can conflict with the Dart formatter, and should not be enabled when the Dart formatter is used.

always_put_required_named_parameters_first

Put required named parameters first.

This rule is available as of Dart 2.0.0.

This rule has a quick fix available.

Details

DO specify required on named parameter before other named parameters.

BAD:

m({b, c, required a}) ;

GOOD:

m({required a, b, c}) ;

BAD:

m({b, c, @required a}) ;

GOOD:

m({@required a, b, c}) ;

always_require_non_null_named_parameters

Specify @required on named parameters without defaults.

This rule is currently deprecated and available as of Dart 2.0.0.

This rule has a quick fix available.

Details

DO specify @required on named parameters without a default value on which an assert(param != null) is done.

BAD:

m1({a}) {
  assert(a != null);
}

GOOD:

m1({@required a}) {
  assert(a != null);
}

m2({a: 1}) {
  assert(a != null);
}

NOTE: Only asserts at the start of the bodies will be taken into account.

always_specify_types

Specify type annotations.

This rule is available as of Dart 2.0.0.

This rule has a quick fix available.

Incompatible rules: avoid_types_on_closure_parameters, omit_local_variable_types

Details

From the style guide for the flutter repo:

DO specify type annotations.

Avoid var when specifying that a type is unknown and short-hands that elide type annotations. Use dynamic if you are being explicit that the type is unknown. Use Object if you are being explicit that you want an object that implements == and hashCode.

BAD:

var foo = 10;
final bar = Bar();
const quux = 20;

GOOD:

int foo = 10;
final Bar bar = Bar();
String baz = 'hello';
const int quux = 20;

NOTE: Using the the @optionalTypeArgs annotation in the meta package, API authors can special-case type variables whose type needs to by dynamic but whose declaration should be treated as optional. For example, suppose you have a Key object whose type parameter you’d like to treat as optional. Using the @optionalTypeArgs would look like this:

import 'package:meta/meta.dart';

@optionalTypeArgs
class Key<T> {
 ...
}

main() {
  Key s = Key(); // OK!
}

annotate_overrides

Annotate overridden members.

This rule is available as of Dart 2.0.0.

Rule sets: recommended, flutter

This rule has a quick fix available.

Details

DO annotate overridden methods and fields.

This practice improves code readability and helps protect against unintentionally overriding superclass members.

BAD:

class Cat {
  int get lives => 9;
}

class Lucky extends Cat {
  final int lives = 14;
}

GOOD:

abstract class Dog {
  String get breed;
  void bark() {}
}

class Husky extends Dog {
  @override
  final String breed = 'Husky';
  @override
  void bark() {}
}

avoid_annotating_with_dynamic

Avoid annotating with dynamic when not required.

This rule is available as of Dart 2.0.0.

This rule has a quick fix available.

Details

AVOID annotating with dynamic when not required.

As dynamic is the assumed return value of a function or method, it is usually not necessary to annotate it.

BAD:

dynamic lookUpOrDefault(String name, Map map, dynamic defaultValue) {
  var value = map[name];
  if (value != null) return value;
  return defaultValue;
}

GOOD:

lookUpOrDefault(String name, Map map, defaultValue) {
  var value = map[name];
  if (value != null) return value;
  return defaultValue;
}

avoid_as

Avoid using as.

This rule has been removed as of the latest Dart releases.

Details

AVOID using as.

If you know the type is correct, use an assertion or assign to a more narrowly-typed variable (this avoids the type check in release mode; as is not compiled out in release mode). If you don’t know whether the type is correct, check using is (this avoids the exception that as raises).

BAD:

(pm as Person).firstName = 'Seth';

GOOD:

if (pm is Person)
  pm.firstName = 'Seth';

but certainly not

BAD:

try {
   (pm as Person).firstName = 'Seth';
} on CastError { }

Note that an exception is made in the case of dynamic since the cast has no performance impact.

OK:

HasScrollDirection scrollable = renderObject as dynamic;

avoid_bool_literals_in_conditional_expressions

Avoid bool literals in conditional expressions.

This rule is available as of Dart 2.0.0.

Details

AVOID bool literals in conditional expressions.

BAD:

condition ? true : boolExpression
condition ? false : boolExpression
condition ? boolExpression : true
condition ? boolExpression : false

GOOD:

condition || boolExpression
!condition && boolExpression
!condition || boolExpression
condition && boolExpression

avoid_catches_without_on_clauses

Avoid catches without on clauses.

This rule is available as of Dart 2.0.0.

Details

AVOID catches without on clauses.

Using catch clauses without on clauses make your code prone to encountering unexpected errors that won’t be thrown (and thus will go unnoticed).

BAD:

try {
 somethingRisky()
}
catch(e) {
  doSomething(e);
}

GOOD:

try {
 somethingRisky()
}
on Exception catch(e) {
  doSomething(e);
}

avoid_catching_errors

Don’t explicitly catch Error or types that implement it.

This rule is available as of Dart 2.0.0.

Details

DON’T explicitly catch Error or types that implement it.

Errors differ from Exceptions in that Errors can be analyzed and prevented prior to runtime. It should almost never be necessary to catch an error at runtime.

BAD:

try {
  somethingRisky();
} on Error catch(e) {
  doSomething(e);
}

GOOD:

try {
  somethingRisky();
} on Exception catch(e) {
  doSomething(e);
}

avoid_classes_with_only_static_members

Avoid defining a class that contains only static members.

This rule is available as of Dart 2.0.0.

Details

From Effective Dart:

AVOID defining a class that contains only static members.

Creating classes with the sole purpose of providing utility or otherwise static methods is discouraged. Dart allows functions to exist outside of classes for this very reason.

BAD:

class DateUtils {
  static DateTime mostRecent(List<DateTime> dates) {
    return dates.reduce((a, b) => a.isAfter(b) ? a : b);
  }
}

class _Favorites {
  static const mammal = 'weasel';
}

GOOD:

DateTime mostRecent(List<DateTime> dates) {
  return dates.reduce((a, b) => a.isAfter(b) ? a : b);
}

const _favoriteMammal = 'weasel';

avoid_double_and_int_checks

Avoid double and int checks.

This rule is available as of Dart 2.0.0.

Details

AVOID to check if type is double or int.

When compiled to JS, integer values are represented as floats. That can lead to some unexpected behavior when using either is or is! where the type is either int or double.

BAD:

f(num x) {
  if (x is double) {
    ...
  } else if (x is int) {
    ...
  }
}

GOOD:

f(dynamic x) {
  if (x is num) {
    ...
  } else {
    ...
  }
}

avoid_equals_and_hash_code_on_mutable_classes

Avoid overloading operator == and hashCode on classes not marked @immutable.

This rule is available as of Dart 2.6.0.

Details

AVOID overloading operator == and hashCode on classes not marked @immutable.

If a class is not immutable, overloading operator == and hashCode can lead to unpredictable and undesirable behavior when used in collections. See https://dart.dev/guides/language/effective-dart/design#avoid-defining-custom-equality-for-mutable-classes for more information.

BAD:

class B {
  String key;
  const B(this.key);
  @override
  operator ==(other) => other is B && other.key == key;
  @override
  int get hashCode => key.hashCode;
}

GOOD:

@immutable
class A {
  final String key;
  const A(this.key);
  @override
  operator ==(other) => other is A && other.key == key;
  @override
  int get hashCode => key.hashCode;
}