avoid_commented_out_code

v0.3.0WarningFixConfigurableCode Quality

Flags comments that look like commented-out Dart code rather than descriptive text — function bodies, variable declarations, imports, calls. The quick fix removes the flagged block.

Version control already preserves the old code. A commented-out block only tells the next reader that someone was unsure, without telling them what about.

This rule is in the opinionated preset and works with its defaults.

Don’t

class Uploader {
  Future<void> upload(String path) async {
    await _put(path);
    // await _put(path, retries: 3);
    // if (!ok) {
    //   throw StateError('upload failed');
    // }
  }

  Future<void> _put(String path, {int retries = 0}) async {}
}

Do

Delete it. git log -p has the version you were keeping:

class Uploader {
  Future<void> upload(String path) async {
    await _put(path);
  }

  Future<void> _put(String path, {int retries = 0}) async {}
}

More examples

Prose is not reported

An explanation stays. Only blocks that read as Dart are flagged:

class Uploader {
  // Retries are handled by the transport layer, not here — see the
  // retry policy in lib/src/net/policy.dart.
  Future<void> upload(String path) async {}
}

Doc comments (///) are never examined at all, whatever they contain.

Tolerate a single commented line

The default min_lines: 1 reports every block, including one-liners. Raise it if a lone commented line is acceptable in your codebase but a whole block is not:

rules:
  avoid_commented_out_code:
    min_lines: 3

class Uploader {
  Future<void> upload(String path) async {
    // await _put(path, retries: 3);   // not reported with min_lines: 3
    await _put(path);
  }

  Future<void> _put(String path, {int retries = 0}) async {}
}

Blocks end at a blank line or at code

A blank line ends a block, and so does any code between two comments. That matters for min_lines: these are three blocks of one line each, not one block of three.

void run() {
  // final a = 1;

  // final b = 2;
  print('go');
  // final c = 3;
}

A comment trailing code (foo(); // note) is its own block too, since it annotates the line beside it.

Known limitations

Detection is a heuristic: a block is reported when at least half its non-empty lines look like Dart rather than prose.

That cuts both ways. A single commented-out line surrounded by explanatory prose may not reach the ratio and stays silent. Prose that reads like code (// returns null;) can be reported — suppress it with // ignore: many_lints/avoid_commented_out_code.

At most 500 comment lines per file are examined, so a generated file with thousands of them does not stall the analysis server.

many_lints:
  rules:
    avoid_commented_out_code:
      min_lines: 2

rules:
  avoid_commented_out_code:
    min_lines: 2

Option	Type	Default	Description
`min_lines`	int	`1`	Minimum number of consecutive commented-out lines before a block is reported

Turning this rule off

This rule is in the opinionated preset, so it is on with preset: opinionated, or by name:

rules:
  avoid_commented_out_code: true

To turn it off again:

rules:
  avoid_commented_out_code: false

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

avoid_accessing_other_classes_private_members — Make the underscore mean what everyone reads it as.
avoid_complex_conditions — Keep boolean conditions within an operand budget.
avoid_deep_nesting — Keep control flow within a nesting budget.
avoid_default_tostring — Don’t interpolate objects that don’t override toString.