Line comment holds a commented-out statement
ID |
dart.maintainability.commented_out_code |
Severity |
info |
Remediation Complexity |
trivial |
Remediation Risk |
low |
Remediation Effort |
low |
Resource |
Dead Code |
Language |
Dart |
Description
Reports a line comment whose whole content is a Dart statement - a call, an assignment, or a statement opening with var, final, return, if, for and the like, ending in a semicolon. Prose comments, documentation comments and TODO notes are not reported.
Rationale
Commented-out code is the most misleading kind of dead code, because it looks maintained. A reader cannot tell whether it is a fix in progress, a deliberate rollback, or a line someone disabled years ago and forgot, so every reader has to work that out again. It is also invisible to the compiler and the analyzer: it is never type-checked, never refactored with the code around it, and never covered by a test, so by the time anyone tries to restore it, it no longer compiles. Version control already keeps the history the comment is trying to preserve.
The following code illustrates the pattern detected by this rule:
/// Computes the order total.
/// The tax rate comes from the caller.
class Totals {
num total(List<num> lines, num rate) {
var sum = 0.0;
for (final line in lines) {
sum += line;
}
// FLAGGED: Line comment holds a commented-out statement
// sum = applyDiscount(sum);
// FLAGGED: Line comment holds a commented-out statement
// print('sum is $sum');
// FLAGGED: Line comment holds a commented-out statement
// if (rate > 0.5) throw StateError('rate too high');
// FLAGGED: Line comment holds a commented-out statement
// final tax = sum * rate;
// FLAGGED: Line comment holds a commented-out statement
// return sum + tax;
// Rounding is deliberate: the ledger stores cents.
// TODO: charge tax per line once the tables land.
// See applyDiscount for the tiers we used to support.
return sum * (1 + rate);
}
}Remediation
Delete the commented-out lines - the history is in version control, and git log/git blame will find them if they are ever needed. If the code is disabled on purpose, express that in code rather than in a comment: put it behind a feature flag or a kDebugMode guard, or leave a short comment saying why it is gone and what replaced it.