dart-code-metrics-annotations

DCM Annotations

DCM is an advanced linter for Dart and Flutter that helps you analyze and improve your code quality. You can find all available lint rules here.

@Throws()

Used to annotate getters, methods, functions, parameters or local variables that can throw an exception (or multiple exceptions/errors) and therefore an invocation of such declarations must explicitly handle that exception.

For example:

@Throws()
void fn() { /* ... */ }

@Throws({IndexError})
void anotherFn() { /* ... */ }

void main() {
  try {
    fn(); // OK.
  } catch(_) {}

  fn(); // LINT.

  try {
    anotherFn(); // OK.
  } catch(_) {}

  try {
    anotherFn(); // LINT.
  } on Exception catch(_) {}
}

DCM will provide feedback if:

• an invocation of a declaration with this annotation has unhandled exceptions
• a declaration is not marked with this annotation, but can throw an exception
• a declaration is marked with this annotation, but does not have any invocation that throws an exception

For more information, see the documentation for handle-throwing-invocations and prefer-correct-throws.

@AcceptedTypes()

Used to annotate fields or parameters that have a type Object, but should only receive a known subset of types (e.g. String and int).

For example:

void fn() {
  fn(1); // LINT
  SomeClass(false); // LINT
}

void fn(@AcceptedTypes({String, bool}) Object value) {}

class SomeClass {
  @AcceptedTypes({String, int})
  final Object field;

  const SomeClass(this.field);
}

DCM will provide feedback if an invocation receives an argument that does not match the type listed in the @AcceptedTypes().

For more information, see the documentation for pass-correct-accepted-types.

@mutated

Used to annotate parameters or variables that are changed/updated within the function/method body.

For example, the avoid-collection-mutating-methods and avoid-mutating-parameters rules will not trigger on annotated parameters and avoid-not-assignable-collection-types will include such parameters into its analysis.

DCM will provide feedback if the @mutated annotation is missing or unnecessary.

For more information, see the documentation for prefer-correct-mutated and other rules mentioned above.

How to use annotations

Take these steps to use annotations:

1. Install this package as a regular dependency:

   dart pub add dart_code_metrics_annotations
   

   or:

   flutter pub add dart_code_metrics_annotations
   

2. Enable rules that rely on DCM annotations and add those annotations to your code.