Dart Code Metrics

Configuration | Rules | Metrics | Anti-patterns

Dart Code Metrics is a static analysis tool that helps you analyse and improve your code quality.

• Reports code metrics
• Provides additional rules for the dart analyzer
• Checks for anti-patterns
• Can be used as CLI, analyzer plugin or library

Links

• See CHANGELOG.md for major/breaking updates, and releases for a detailed version history.
• To contribute, please read CONTRIBUTING.md first.
• Please open an issue if anything is missing or unclear in this documentation.

Usage

Analyzer plugin

A plugin for the Dart analyzer package providing additional rules from Dart Code Metrics. All issues produced by rules or anti-patterns will be highlighted in IDE.

1. Install package as a dev dependency

   $ dart pub add --dev dart_code_metrics
   
   # or for a Flutter package
   $ flutter pub add --dev dart_code_metrics

   OR

   add it manually to pubspec.yaml

   dev_dependencies:
     dart_code_metrics: ^3.0.0

   and then run

   $ dart pub get
   
   # or for a Flutter package
   $ flutter pub get

2. Add configuration to analysis_options.yaml

   analyzer:
     plugins:
       - dart_code_metrics
   
   dart_code_metrics:
     anti-patterns:
       - long-method
       - long-parameter-list
     metrics:
       cyclomatic-complexity: 20
       lines-of-executable-code: 50
       number-of-parameters: 4
       maximum-nesting-level: 5
     metrics-exclude:
       - test/**
     rules:
       - newline-before-return
       - no-boolean-literal-compare
       - no-empty-block
       - prefer-trailing-comma
       - prefer-conditional-expressions
       - no-equal-then-else

3. Reload IDE to allow the analyzer to discover the plugin

CLI

The package can be used as a command-line tool. It will produce a result in one of the supported formats:

• Plain terminal
• GitHub
• Codeclimate
• HTML
• JSON

Basic usage

Install the package as listed in the Analyzer plugin usage example.

If you want the command-line tool to check rules, you should configure rules entry in the analysis_options.yaml first.

dart pub run dart_code_metrics:metrics lib

# or for a Flutter package
flutter pub run dart_code_metrics:metrics lib

Global usage

dart pub global activate dart_code_metrics
dart pub global run dart_code_metrics:metrics lib

# or for a Flutter package
flutter pub global activate dart_code_metrics
flutter pub global run dart_code_metrics:metrics lib

Options

Usage: metrics [arguments...] <directories>

-h, --help                                        Print this usage information.


-r, --reporter=<console>                          The format of the output of the analysis
                                                  [console (default), console-verbose, codeclimate, github, gitlab, html, json]
-o, --output-directory=<OUTPUT>                   Write HTML output to OUTPUT
                                                  (defaults to "metrics")


    --cyclomatic-complexity=<20>                  Cyclomatic Complexity threshold
    --lines-of-code=<100>                         Lines of Code threshold
    --maximum-nesting-level=<5>                   Maximum Nesting Level threshold
    --number-of-methods=<10>                      Number of Methods threshold
    --number-of-parameters=<4>                    Number of Parameters threshold
    --weight-of-class=<0.33>                      Weight Of a Class threshold
    --lines-of-executable-code=<50>               Lines of executable code threshold


    --root-folder=<./>                            Root folder
                                                  (defaults to current directory)
    --exclude=<{/**.g.dart,/**.template.dart}>    File paths in Glob syntax to be exclude
                                                  (defaults to "{/**.g.dart,/**.template.dart}")


    --set-exit-on-violation-level=<warning>       Set exit code 2 if code violations same or higher level than selected are detected
                                                  [noted, warning, alarm]

Library

See example/example.dart.

Configuration

To configure the package add the dart_code_metrics entry to the analysis_options.yaml and update plugins list of the analyzer.

analyzer:
  plugins:
    - dart_code_metrics

dart_code_metrics:
  anti-patterns:
    - ... # add this entry to configure the list of anti-patterns
  metrics:
      ... # add this entry to configure the list of reported metrics
  metrics-exclude:
    - ... # add this entry to configure the list of files that should be ignored by metrics
  rules:
    - ... # add this entry to configure the list of rules

Basic config example:

analyzer:
  plugins:
    - dart_code_metrics

dart_code_metrics:
  anti-patterns:
    - long-method
    - long-parameter-list
  metrics:
    cyclomatic-complexity: 20
    lines-of-executable-code: 50
    number-of-arguments: 4
    maximum-nesting-level: 5
  metrics-exclude:
    - test/**
  rules:
    - newline-before-return
    - no-boolean-literal-compare
    - no-empty-block
    - prefer-trailing-comma
    - prefer-conditional-expressions
    - no-equal-then-else

Configuring a rules entry

To enable a rule add its id to the rules entry. All rules have severity which can be overridden with severity config entry. For example,

dart_code_metrics:
  rules:
    - newline-before-return
        severity: info

will set severity to info. Available severity values: none, style, performance, warning, error.

Rules with a configurable badge have additional configuration, check out their docs for more information.

Configuring a metrics entry

To enable a metric add its id to the metrics entry in the analysis_options.yaml. All metrics can take a threshold value. If no value was provided, the default value will be used.

Configuring a metrics-exclude entry

To exclude files from a metrics report provide a list of regular expressions for ignored files. For example:

dart_code_metrics:
  metrics-exclude:
    - test/**
    - lib/src/some_file.dart

Configuring an anti-pattern entry

To enable an anti-pattern add its id to the anti-patterns entry.

Ignoring a rule or anti-pattern

If a specific rule or anti-pattern warning should be ignored, it can be flagged with a comment. For example,

// ignore: no-empty-block
void emptyFunction() {}

tells the analyzer to ignore this instance of the no-empty-block warning.

End-of-line comments are supported as well. The following communicates the same thing:

void emptyFunction() {} // ignore: no-empty-block

To ignore a rule for an entire file, use the ignore_for_file comment flag. For example,

// ignore_for_file: no-empty-block
...

void emptyFunction() {}

tells the analyzer to ignore all occurrences of the camel_case_types warning in this file.

It's the same approach that the dart linter package use.

Additionally, exclude entry for the analyzer config can be used to ignore files. For example,

exclude:
  - example/**

will work both for the analyzer and for this plugin.

Metrics

Metrics configuration is described here.

Available metrics:

• Cyclomatic Complexity
• Lines of Code
• Maximum Nesting
• Number of Parameters
• Number of Methods
• Weight of a Class
• Lines of Executable Code

Rules

Rules are grouped by a category to help you understand their purpose.

Right now auto-fixes are available through an IDE context menu (ex. VS Code Quick Fix).

Rules configuration is described here.

Common

• avoid-unused-parameters
• binary-expression-operand-order  
• double-literal-format  
• member-ordering  
• member-ordering-extended  
• newline-before-return
• no-boolean-literal-compare  
• no-empty-block
• no-equal-arguments
• no-equal-then-else
• no-magic-number  
• no-object-declaration
• prefer-conditional-expressions  
• prefer-trailing-comma    

Flutter specific

• avoid-returning-widgets

Intl specific

• prefer-intl-name  
• provide-correct-intl-args

Angular specific

• avoid-preserve-whitespace-false
• component-annotation-arguments-ordering  
• prefer-on-push-cd-strategy

Anti-patterns

Like rules, anti-patterns display issues in IDE, except that their configuration is based on a metrics entry in the config.

• long-method
• long-parameter-list

Troubleshooting

Please read the following guide if the plugin is not working as you'd expect it to work.

Contributing

If you are interested in contributing, please check out the contribution guidelines. Feedback and contributions are welcome!

LICENCE

MIT