Forem: Dmitry Zhifarsky

Finding Unused Files With Dart Code Metrics

Dmitry Zhifarsky — Sat, 12 Jun 2021 09:11:32 +0000

In our previous article, we announced Dart Code Metrics, a static code analysis tool. Initially, its task was to collect and represent code metrics, as well as provide additional rules for the analyzer with a more flexible configuration. However, we decided to push it to the next level.

In this article, we’ll go over one of the first commands, check-unused-files, to search for unused Dart files.

$ dart run dart_code_metrics:metrics check-unused-files lib

# or for a Flutter package
$ flutter pub run dart_code_metrics:metrics check-unused-files lib

Full command description:

Check unused *.dart files.

Usage: metrics check-unused-files [arguments] <directories>
-h, --help                                        Print this usage information.


-r, --reporter=<console>                          The format of the output of the analysis.
                                                  [console (default), json]


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

When will you need to search for unused files?

Two scenarios come to mind right away:

When you need to do a step-by-step refactoring on a large codebase with moving files and it's difficult to know if all the files are being used correctly
Code generation, which creates extra files, is popular in Dart. Sometimes it can be difficult to know if these files are no longer in use.

So what’s under the hood?

The search for unused files starts with listing the files within the passed (sub)directories. Then we check the list of imports, exports, and part-directives in each file. If the imported/exported file belongs to this package, then it’s marked accordingly: “in use.” Files with exports or the main function are separately marked as entry points and “in use.”

After that, unused files are displayed in the following format:

Unused file: <path_to_file>
   ...
Unused file: <path_to_file>

Total unused files - N

Let's take a project with the following structure:

 lib/
   src/
     entry_point.dart
     first_file.dart
     second_file.dart

And with file content like this:

entry_point.dart

import 'first_file.dart';

void main() {
  ... // some code
}

first_file.dart

class SomeClass {
  ... // some code
}

second_file.dart

import 'first_file.dart';

class SomeOtherClass {
  ... // some code
}

Now we can call the command:

$ dart run dart_code_metrics:metrics check-unused-files lib

In the first step, the algorithm will determine that there are only three files in the project and will scan them first. After entry_point.dart is scanned, first_file.dart is marked as “in use” because it’s imported into entry_point.dart. This will mark entry_point.dart as “in use” since it declares the main function. Next, the algorithm will check first_file.dart, which has no directives, and then second_file.dart. Since second_file.dart doesn’t import any of the previous files, it’ll be marked as unused.

We can exclude second_file.dart from the results by passing the --exclude option:

$ dart run dart_code_metrics:metrics check-unused-files lib --exclude=”lib/**/second_file.dart”

In this case, the command will output:

No unused files found!

The command is available during the installation of the pre-release version, 4.0.0-dev.4.

Why did we decide to make a separate command, not add a search for used files to the existing call, and not provide support for the analyzer plugin? Because finding unused files seems to be an infrequent feature, while constantly checking is definitely overhead.

The previous call to code analyzer is now also available via the analyze command. If you used to call CLI with:

$ dart run dart_code_mertics:metrics lib

It’ll now look like this:

$ dart run dart_code_mertics:metrics analyze lib.

In version 4.0, we have support for dart run dart_code_mertics:metrics lib. It’ll work at least up to version 5.0, so no changes will be required to CI after transitioning to a newer version.

We’d love to hear your feedback and ideas on the new rules, metrics, or commands! You can always reach us via the community chat on Telegram or post the issue on GitHub.

This command is just a part of the 4.0 release, which also includes new rules. We’ll discuss them in the next article.

P.S. We are currently working on adding new commands and the next candidate is a command to check unused mocks in a project (might help with cases, when you keep all your mocks in a single file and they eventually become unused). Please let us know what do you think about this command, will it be useful for you?

Improving Code Quality With Dart Code Metrics

Dmitry Zhifarsky — Thu, 27 May 2021 19:44:18 +0000

Dart Code Metrics is a static code analysis tool that allows you to collect code metrics and provide additional rules for the analyzer. The tool helps developers monitor the quality of code and improve it. In this article, we'd like to share the capabilities of Dart Code Metrics with the community. This tool helped us at Wrike, and we hope it'll help you, too.

It can be launched via the command line, which is connected as a plugin to the Dart Analysis Server, or as a library. Launching via the command line allows you to easily integrate the tool into the CI/CD process, and you can get results in Сonsole, HTML, JSON, CodeClimate, or GitHub. Connecting the tool as a plugin to the Analysis Server allows you to receive real-time feedback directly from the IDE.

Why did we develop a tool like this? Wrike already has about 2.5 million lines of code written in Dart. A code base like this comes with the price of maintenance - so how do you know when it's time to refactor your code, and what do you start with?

Dart SDK is distributed with an Analyzer, which has a built-in linter with a set of rules. In the official pub, you can also find recommended rulesets: pedantic, effective_dart, etc. This helps us avoid making mistakes and maintain the codebase as suggested by the author of the language. However, we didn't have enough analytical data on the code, and that started it all.

Metrics

After researching materials on evaluating and designing program code, we realized the first step was to implement a collection of software metrics from the code.

Now the analyzer collects the following metrics:

Cyclomatic complexity
Lines of executable code
Lines of code
Number of parameters
Number of methods
Maximum nesting
Weight of class

We set a base threshold value for each metric, after which code refactoring is recommended. At the same time, threshold values can be easily predefined and passed to the tool when either called from the console, or during the plugin configuration for the analyzer via analysis_options.yaml. You can read more about this here.

In the next step the tool finds anti-patterns in the codebase, relying on data from several metrics. Only two anti-patterns are currently implemented - long-method and long-parameter-list - but we'll expand this list in the future.
While metrics like number of parameters or number of methods are easy enough to understand, what about cyclomatic complexity?

The cyclomatic complexity of a piece of code is the number of linearly independent routes in the code. For example, if the source code doesn't contain any branch points or loops, then its complexity is one, since there's only one route through the code. If the code has a single if-statement containing one simple condition, we have two routes through the code: the if-statement is true or false.

Many independent routes in the function body impact the code's readability and maintenance. So it's better to split the function in such cases.

The tool provides various report formats to visualize the metrics. We'll get back to this later in the "Reports" section.

Linting

Initially, the tool only collected metrics, but then we added linting.

Other ecosystems have useful rules like unused arguments check, class member ordering check, etc. They're not available in the built-in Dart SDK linter, so we made our own linter.

Why did we decide to add linting to a separate package instead of making PR in the built-in analyzer? Because we decided to implement extended configuration capabilities. For example, we can configure the exact ordered list of class members that should be checked.

The current list of rules:

General rules

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

For Intl library

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

For Dart Angular

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

You can find the most up-to-date list in the documentation.

Stylistic rules aren't the only important things to consider; we also want to highlight potential errors like no-equal-then-else, no-equal-arguments, and more.

Our rules were partially based on issues that we'd encounter during our reviews. Ideally, we want the issues to be covered automatically so we can focus on the work that matters. Another part of our rules emerged during the process of studying other tools' rules. (Shoutout to PVS-Studio, TSLint, and ESLint for inspiration!)

Let's take a closer look at some of those rules.

Avoid unused parameters. Checks for unused parameters for functions or methods. An unused parameter can indicate that it's no longer needed during refactoring, or that a variable is somewhere in the body of a function (or method) instead of that parameter. In the first case the rule helps remove unused code; the second indicates a possible error.

Here's a simple example:

String method(String value) => "";

The value parameter isn't used here, and the analyzer will display the message "Parameter is unused."

Since Dart allows you to inherit from any class and requires that the parameter be included in the descendants, it can be renamed to _ in the base class, and the analyzer will skip it.

For example:

String method(String _) => "";

Prefer trailing comma. Checks for the trailing comma for arguments, parameters, enumerations, and collections, provided they span multiple lines.

For example:

void firstFunction (String firstArgument, String secondArgument, String thirdArgument) {
  ...
}

For a function like this, the rule will suggest adding a comma at the end so that once formatted it turns into:

void firstFunction(
  String firstArgument,
  String secondArgument,
  String thirdArgument,
) {
  ...
}

If the parameters were initially placed on one line, the analyzer won't consider it an error:

void secondFunction(String arg1, String arg2, String arg3) {
  ...
}

You can also specify a break-on parameter for the rule, which enables additional checking for the specified number of elements. For example, without break-on, the example above is considered correct. But if you configure the rule for break-on: 2, the analyzer will display an error for this function and suggest adding a comma.

No equal arguments. Checks whether the same argument is passed more than once when instantiating a class or calling a method/function.

Suppose there's a certain user class and a separate function that creates this user:

class User {
  final String firstName;
  final String lastName;

  const User(this.firstName, this.lastName);
}

User createUser(String lastName) {
  String firstName = getFirstName();
  return User(
    firstName,
    firstName,
  );
}

Both User class fields are strings, and it's easy to miss that the same variable is passed when you create it. In such cases, the rule will indicate the variable firstName is passed more than once, which may be an error.

Member ordering extended. The rule checks the class member order. The rule received an extended postfix since we already had a member ordering rule, but it wasn't as flexible.

The rule accepts an ordering configuration with quite a flexible template. It allows you to specify not just the type of a class member (field, method, constructor), but also keywords such as late, const, final, or, for example, nullable.

The configuration can look like this:

public-late-final-fields
private-late-final-fields
public-nullable-fields
private-nullable-fields
named-constructors
factory-constructors
getters
setters
public-static-methods
private-static-methods
protected-methods
etc.

Or be simplified to:

fields
methods
setters
getters (or, if there's no need to separate, just getters-setters)
constructors

Read more about the rule's capabilities in the documentation.
Additionally, the rule may require alphabetical sorting. To do this, you need to pass alphabetize: true to its configuration.

Reports

To visualize all the collected metrics and linting results, the tool conveniently provides reports in one of the following formats:

Console
HTML
JSON
CodeClimate
GitHub

Console format is the default, and can be transferred to the console utility via the --reporter flag.

For example:

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

When executing the command on the Dart Code Metrics codebase, we'll receive the following report in the console:

If you want to choose a different type reporter (e.g., HTML), you need to run the following command:

$ dart pub run dart_code_metrics:metrics lib --reporter=html
# or for a Flutter package
$ flutter pub run dart_code_metrics:metrics lib --reporter=html

The report will be generated in the metrics folder. The resulting folder can also be passed using the --output-directory or -o flag:

In the report, you can view each file separately:

To view detailed information on metrics, you need to hover over the icons to the left of the code:

If you're using GitHub Workflows and want to get a report immediately in the created PRs, you need to add a new step to the pipeline:

jobs:
  your_job_name:
  ...
    steps:
    ...
     - name: Run Code Metrics
       run: flutter pub run dart_code_metrics:metrics --reporter=github lib

This will allow you to get reports in this format:

Detailed information about all types of metrics and configuration methods can be found in the documentation.

Installing

If you want to try the package for yourself, here's a short guide on connecting it as a plug-in for Dart analyzer.

Step 1: install the 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 the package manually to pubspec.yaml.

Important: If your package hasn't been migrated to null safety yet, use version 2.5.0.

dev_dependencies:
  dart_code_metrics: ^3.3.3

Run the command to install dependencies.

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

Step 2: Add configuration to analysis_options.yaml.

This configuration specifies the long-method and long-parameter-list anti-patterns, metrics with their threshold values, and rules. The entire list of available metrics can be found here, and the list of rules here.

Step 3: Reload the IDE for the analyzer to detect the plugin.

If you want to use the package as a CLI, check out the documentation here. To use it as a Library, take a look at the documentation here.

Conclusion

Given the popularity of Flutter, we're considering what metrics and rules could help developers with this framework. We're open to suggestions; if you have ideas for rules or metrics that could be useful to Dart or Flutter developers, feel free to write to us or report an issue via GitHub. We'll be happy to make developers' lives better.

Our plans for the future can always be tracked in the public project repository in the issues list or in projects, where you can also leave feedback on the tool.

Feel free to join our community on Telegram!