parameters_ordering

v1.0.0WarningConfigurableCode Organization

Flags a function whose named parameters are not in the order you configure.

A long named-parameter list has the same problem as a long map literal: without an order, checking whether a parameter already exists means reading all of them, and a new one gets appended at the end beside the near-duplicate nobody saw.

Positional parameters are never ordered. They are ordered by meaning and by every call site that depends on them — sorting those would break the code.

This rule is in the pedantic preset, which sets order: alphabetical and lowers min_parameters to 2. Under any other preset it reports nothing until you set order: — a widget constructor deliberately leads with its most important parameters.

many_lints:
  rules:
    parameters_ordering:
      order: alphabetical
      group_required: true
      min_parameters: 5

rules:
  parameters_ordering:
    order: alphabetical
    group_required: true
    min_parameters: 5

Don’t

With order: alphabetical:

class UploadRequest {
  UploadRequest({
    required this.name,
    required this.id,
    this.timeout,
    this.retries,
    this.verbose,
  });

  final String name;
  final String id;
  final Duration? timeout;
  final int? retries;
  final bool? verbose;
}

Do

class UploadRequest {
  UploadRequest({
    required this.id,
    required this.name,
    this.retries,
    this.timeout,
    this.verbose,
  });

  final String name;
  final String id;
  final Duration? timeout;
  final int? retries;
  final bool? verbose;
}

Examples

`required` and optional are sorted as two independent runs

This is the default, group_required: true. Their relative placement belongs to the SDK’s always_put_required_named_parameters_first, so the two rules never report the same issue:

rules:
  parameters_ordering:
    order: alphabetical
    min_parameters: 2

// Accepted — required run is a..b, optional run is x..y; the optional `x`
// following the required `b` is not this rule's business.
void send({required String alpha, required String beta, String? x, String? y}) {}

Set it to false to sort every named parameter as one list instead:

rules:
  parameters_ordering:
    order: alphabetical
    group_required: false
    min_parameters: 2

// Don't — one list now, and `zebra` precedes `apple`
void send({required String zebra, String? apple}) {}

// Do
void send({String? apple, required String zebra}) {}

`min_parameters` keeps short signatures out of it

The default is 5, so a four-parameter signature is never reported:

rules:
  parameters_ordering:
    order: alphabetical

// Not reported — four named parameters, under the default min_parameters: 5
void connect({String? url, int? port, int? retries, bool? secure}) {}

Lower it to check short signatures too — this is what preset: pedantic does:

rules:
  parameters_ordering:
    order: alphabetical
    min_parameters: 2

// Don't — now reported at two parameters
void connect({String? url, int? port}) {}

// Do
void connect({int? port, String? url}) {}

`by_length`

Longest parameter name last. Ties fall back to alphabetical so the order is total:

rules:
  parameters_ordering:
    order: by_length
    min_parameters: 2

// Don't
void render({int? width, int? x, bool? antialias}) {}

// Do
void render({int? x, int? width, bool? antialias}) {}

Options

Option	Type	Default	Description
`order`	string	`—`	`alphabetical`, `alphabetical_case_sensitive` or `by_length`. Unset means the rule is silent
`group_required`	bool	`true`	Sort required and optional named parameters as two independent runs
`min_parameters`	int	`5`	How many named parameters a signature needs before order is checked

Known limitations

Positional parameters do not count towards the threshold. A function with three positional and four named parameters has four for this rule’s purposes, and stays under the default of 5.

With group_required: true, each run is checked against the threshold as a whole list. The count is of all named parameters; the sort then runs separately over the required ones and the optional ones.

A parameter with no name token stops the check. The rest of that run is left alone rather than ordered around something the rule cannot place.

Only the first out-of-order parameter in a run is reported, so one misplaced name does not produce a wall of diagnostics.

No quick fix. Reordering named parameters is safe for callers, but a signature often carries doc comments tied to particular lines, and moving parameters past them silently mismatches the two.

Turning this rule off

To disable this rule:

rules:
  parameters_ordering: false

To keep the rule on but skip certain paths, use per-rule exclude.

arguments_ordering — Keep named arguments in a configured order.
initializers_ordering — Keep constructor initializers in field order.
map_keys_ordering — Keep map literal keys in a configured order.
member_ordering — Keep class members in a configured order.