avoid-positional-boolean-parameters

Same as avoid_positional_boolean_parameters in Dart lints

Group
Style
Path
lint/style/avoid-positional-boolean-parameters
Default
Off, opt in
Origin
Dart lints
Rule
112 of 512

Flags a positional bool parameter in a public signature.

At a call site like setVisible(true) the literal says nothing about what it means. The first positional bool parameter (required or optional) of a public function, method, constructor, or Function(...) type is reported; make it named instead:

void configure(int level, bool verbose) {}   // `bool verbose` flagged
void configure(int level, {bool verbose = false}) {}

Private functions, methods, and constructors (by their own name), getters, method setters, and operators are skipped, as are methods whose signature is fixed by an inherited member they override. Top-level setters are checked like functions. Function(...) types are checked wherever they are written, including in overriding signatures and private declarations; legacy typedef void F(bool b); aliases and function-typed parameters (void f(bool b) as a parameter) are not function types and are skipped. Field and super parameters (this.flag, super.flag) take their declared type. When falcon cannot resolve whether a method overrides something, it stays silent.

Invalid

example.dartdart
void configure(int level, bool verbose) {}

// Only the first positional bool is reported.
void two(bool verbose, bool dryRun) {}

// Optional positional bools count too.
void optional(int level, [bool flag = false]) {}

void nullable(bool? flag) {}

// Top-level setters are functions to the analyzer.
set enabled(bool value) {}

class Widget {
  final bool enabled;
  final bool visible;

  Widget(this.enabled, this.visible);

  Widget.typed(bool enabled, bool visible)
      : enabled = enabled,
        visible = visible;

  void update(bool animate) {}

  static void create(bool a) {}
}

// The unnamed constructor of a private class is public.
class _Private {
  _Private(bool flag);
}

class Base {
  final bool flag;
  Base(this.flag);
  void listen(void Function(bool) callback) {}
}

// Positional super parameters match the super constructor by position.
class Renamed extends Base {
  Renamed(super.other);
}

class Sub extends Base {
  Sub() : super(true);

  // Function types are checked even in overriding signatures.
  @override
  void listen(void Function(bool) callback) {}
}

extension WidgetX on Widget {
  void toggle(bool a) {}
}

typedef Toggle = void Function(int, bool);

void f() {
  void local(bool a) {}
  local(true);
  _Private(true);
}

void annotated(
  @Deprecated('use named')
  bool flag,
) {}

class Updatable {
  void update(bool animate) {}
}

class Overriding extends Updatable {
  // Overrides keep the inherited signature.
  @override
  void update(bool animate) {}
}

class Unannotated extends Updatable {
  // An override without the annotation is still detected.
  void update(bool animate) {}
}

class PrimaryBoolean(bool enabled);

class DeclaringPrimaryBoolean(final bool enabled);

// Extension-type representation parameters are primary constructor parameters.
extension type BooleanRepresentation(bool enabled) {}
`bool` parameters should be named parameters.
1void configure(int level, bool verbose) {}
`bool` parameters should be named parameters.
3// Only the first positional bool is reported.
4void two(bool verbose, bool dryRun) {}
`bool` parameters should be named parameters.
6// Optional positional bools count too.
7void optional(int level, [bool flag = false]) {}
`bool` parameters should be named parameters.
8
9void nullable(bool? flag) {}
`bool` parameters should be named parameters.
11// Top-level setters are functions to the analyzer.
12set enabled(bool value) {}
`bool` parameters should be named parameters.
17
18 Widget(this.enabled, this.visible);
`bool` parameters should be named parameters.
19
20 Widget.typed(bool enabled, bool visible)
`bool` parameters should be named parameters.
23
24 void update(bool animate) {}
`bool` parameters should be named parameters.
25
26 static void create(bool a) {}
`bool` parameters should be named parameters.
30class _Private {
31 _Private(bool flag);
`bool` parameters should be named parameters.
35 final bool flag;
36 Base(this.flag);
`bool` parameters should be named parameters.
36 Base(this.flag);
37 void listen(void Function(bool) callback) {}
`bool` parameters should be named parameters.
41class Renamed extends Base {
42 Renamed(super.other);
`bool` parameters should be named parameters.
49 @override
50 void listen(void Function(bool) callback) {}
`bool` parameters should be named parameters.
53extension WidgetX on Widget {
54 void toggle(bool a) {}
`bool` parameters should be named parameters.
56
57typedef Toggle = void Function(int, bool);
`bool` parameters should be named parameters.
59void f() {
60 void local(bool a) {}
`bool` parameters should be named parameters.
65void annotated(
66 @Deprecated('use named')
`bool` parameters should be named parameters.
70class Updatable {
71 void update(bool animate) {}
`bool` parameters should be named parameters.
84
85class PrimaryBoolean(bool enabled);
`bool` parameters should be named parameters.
86
87class DeclaringPrimaryBoolean(final bool enabled);
`bool` parameters should be named parameters.
89// Extension-type representation parameters are primary constructor parameters.
90extension type BooleanRepresentation(bool enabled) {}

Valid

example.dartdart
// Named bools are fine.
void configure({bool verbose = false, bool dryRun = false}) {}

void mixed(int first, {required bool second}) {}

// Private declarations are skipped.
void _private(bool a) {}

class Base {
  void _hidden(bool a) {}

  Base._internal(bool a);
  Base();

  // Getters, method setters, and operators are skipped.
  set flag(bool value) {}
  bool get flag => true;
  bool operator ==(Object other) => true;
  int get hashCode => 0;
}

class Sub extends Base {
  Sub() : super();

  // A private constructor is skipped.
  Sub._(bool a);
}

// Legacy typedefs and function-typed parameters are not function types.
typedef void Legacy(bool a);

void takes(void callback(bool a)) {}

void nonBool(int a, String b, Object c) {}

void main() {
  _private(true);
  Base._internal(true);
  Sub._(true);
}

class NamedPrimaryBoolean({bool enabled = false});

class PrivatePrimaryBoolean._hidden(bool enabled);

Configure avoid-positional-boolean-parameters

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

falcon.jsonjson
{
  "linter": {
    "rules": {
      "style": {
        "avoid-positional-boolean-parameters": "error"
      }
    }
  }
}

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

example.dartdart
// falcon-ignore lint/style/avoid-positional-boolean-parameters: <reason>