[Open source, Программирование, Dart, Flutter] Повышаем качество кода с Dart Code Metrics

Ответить на тему

Автор

Сообщение

news_bot ^®

Стаж: 6 лет 9 месяцев
Сообщений: 27286

news_bot ^® написал(а)
13-Апр-2021 17:30

Цитировать

Dart Code Metrics — это инструмент статического анализа кода, который позволяет собирать метрики по коду и предоставляет дополнительные правила для анализатора. Основная задача — помогать разработчикам следить за качеством кода и улучшать его. В этой статье мы хотим поделиться возможностями инструмента с сообществом. Он помог нам в Wrike решить часть проблем на фронтенде, и, надеемся, поможет и вам.Инструмент можно запускать из командной строки, подключать в виде плагина к Dart Analysis Server, а также в виде библиотеки. Запуск из командной строки позволяет легко интегрировать инструмент в процесс CI/CD, при этом результат анализа можно получить в одном из форматов: Сonsole, HTML, JSON, CodeClimate, GitHub. Подключение в виде плагина к Analysis Server позволяет получать оперативную обратную связь непосредственно в IDE.Зачем мы решили создать такой инструмент? В Wrike уже написано примерно 2.5 миллиона строк кода на Dart. При таком размере кодовой базы невольно задумываешься о том, какова цена поддержки такого объема кода, как понять, что пора проводить рефакторинг, и с каких мест его стоит начать. Вместе с Dart SDK нам поставляется Analyzer, у которого есть встроенный линтер с богатым набором правил. В официальном pub вы также можете встретить рекомендованные наборы правил: pedantic, effective_dart и т.д. Это помогает нам избежать глупых ошибок и поддерживать кодовую базу в той стилистике, которую предлагают авторы языка. Но мы столкнулись с тем, что нам не хватало аналитической информации по коду, а дальше завертелось.МетрикиИз книг и статей про оценку и дизайн программного кода (например, отсюда) мы поняли, что первый шаг, который нужно сделать, — реализовать сбор метрик с кода. Сейчас анализатор собирает такие метрики:

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

Для каждой метрики мы задали базовое пороговое значение, после которого рекомендуется провести рефакторинг кода. При этом пороговые значения могут быть легко предопределены и переданы инструменту при вызове из консоли или при конфигурации плагина для анализатора через analysis_options.yaml, подробнее про это можно почитать здесь.Следующий шаг — опираясь на данные нескольких метрик, инструмент находит антипаттерны в кодовой базе. На текущий момент реализовано всего два антипаттерна — long-method и long-parameter-list. Мы думаем о том, чтобы расширить этот список.Если с метриками типа Number of Parameters или Number of Methods достаточно легко разобраться, то как же считается, например, Cyclomatic Complexity? Цикломатическая сложность части программного кода — это количество линейно независимых маршрутов через программный код. Например, если исходный код не содержит никаких точек ветвления или циклов, то сложность равна единице, поскольку есть только единственный маршрут через код. Если код имеет единственный оператор if, содержащий простое условие, то существует два пути через код: первый — если условие оператора if имеет значение true, второй — если false. Подробнее про цикломатическую сложность можно почитать в статье на Википедии.Большое количество независимых маршрутов в теле функции оказывает влияние на его читаемость и поддержку, поэтому в таких случаях предпочтительнее разбивать функцию на несколько.Для визуализации собранных метрик инструмент предоставляет различные форматы отчетов, подробнее о них я расскажу в части «Отчеты».ПравилаИзначально инструмент собирал только метрики, но мы решили пойти дальше и добавить линтинг. В других экосистемах есть полезные правила: например, проверка неиспользуемых аргументов, порядок членов класса и другие. Во встроенном дартовом линтере их нет, поэтому мы сделали свои.Почему мы решили добавить линтинг в отдельный пакет, а не сделать PR во встроенный анализатор? У нас иначе спроектированы правила — наличие расширенной конфигурации, возможность для каждого правила настроить строгость проверки. Например, error будет «валить» пайплайн, в то время как warning или style — нет.Текущий список правил выглядит так:Общие

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

Специально для использования с библиотекой Intl

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

Специально под Dart Angular

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

Актуальный список вы всегда можете посмотреть в документации.Речь идет не только про стилистические правила, но и про те, которые подсвечивают потенциальные ошибки: например, no-equal-then-else, no-equal-arguments и другие.Часть наших правил основаны на проблемах, с которыми мы сталкиваемся на ревью и которые хотим покрывать автоматически, чтобы иметь возможность сосредотачиваться на самом главном. Другая часть появилась в процессе изучения списка правил таких инструментов, как PVS-Studio, TSLint, ESLint (большое спасибо им за вдохновение).Рассмотрим подробнее некоторые из них.Avoid unused parameters. Проверяет наличие неиспользуемых параметров у функций или методов. Наличие неиспользуемого параметра может говорить как о том, что параметр перестал быть нужен в ходе рефакторинга, так и том, что где-то в теле функции или метода используется какая-то переменная вместо него. Если в первой ситуации правило помогает убрать неиспользуемый код, то во второй — указывает на возможную ошибку.Простой пример:

String method(String value) => “”;

Здесь параметр value не используется, и для него анализатор выведет сообщение “Parameter is unused”.Учитывая то, что в Dart можно наследоваться от любого класса и параметр может быть необходим в наследниках, в базовом классе он может быть переименован в _ . Тогда анализатор его пропустит.Например:

String method(String _) => “”;

Prefer trailing comma. Проверяет последнюю запятую для аргументов, параметров, перечислений и коллекций при условии, что они занимают несколько строк. Например:

void function(
String firstArgument, String secondArgument, String thirdArgument) {
return;
}

Для такой функции правило предложит добавить в конец запятую, чтобы после форматирования она превратилась в:

void function(
  String firstArgument,
  String secondArgument,
  String thirdArgument,
) {
  return;
}

Если параметры изначально помещались на одной строке, то анализатор не будет считать это ошибкой:

void function(String arg1, String arg2, String arg3) {
return;
}

Для правила также можно указать параметр break-on, который включает дополнительную проверку для указанного количества элементов. Например, без параметра break-on пример выше считается корректным. Но если сконфигурировать правило на break-on: 2, то анализатор покажет ошибку для этой функции и предложит добавить запятую.No equal arguments. Проверяет передачу одного и того же аргумента более одного раза при создании инстанса класса или вызове метода/функции.Предположим, что существует некоторый класс 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,
  );
}

Оба поля класса User являются строкам. Легко не заметить, что при его создании передается одна и та же переменная. В таких случаях правило покажет, что переменная firstName передается более одного раза, и это может быть ошибкой.Member ordering extended. Проверяет порядок членов класса. Это правило получило постфикс extended: у нас уже было правило Member ordering, но оно было не настолько гибким.Правило принимает конфигурацию порядка по достаточно гибкому шаблону. Он позволяет указывать не только тип члена класса (поле, метод, конструктор и др.), но и такие ключевые слова, как late, const, final или, например, признак nullable. Конфигурация может быть задана, например, так:- 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.Или упрощена до: - fields- methods- setters- getters (или просто **getters-setters** если нет необходимости разделять)- constructorsПодробнее про возможности правила можно почитать в документации. Дополнительно правило может требовать сортировку по алфавиту. Для этого в его конфигурацию нужно передать `alphabetize: true`.ОтчетыДля удобной визуализации собранных метрик и результатов линтинга инструмент предоставляет отчеты в одном из следующих форматов:

Console
HTML
JSON
CodeClimate
GitHub

Консольный формат является форматом по-умолчанию, формат может быть передан консольной утилите с помощью флага --reporter.Например, при выполнении команды:

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

При выполнении команды на кодовой базе Dart Code Metrics мы получили такой отчет в консоль:

Если захотим выбрать другой тип репортера (например, HTML), то нужно выполнить следующую команду:

$ 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

Сгенерируется отчет в папке metrics. Результирующую папку также можно передать с помощью флага --output-directory или -o:

В отчете можно посмотреть каждый файл отдельно:

Чтобы посмотреть подробную информацию по метрикам, нужно навести курсор на значки слева от кода:

Если вы используете GitHub Workflows и хотите получить репорт сразу в созданных PR, необходимо добавить в пайплайн новый шаг:

jobs:
  your_job_name:
    ...
    steps:
     ...
      - name: Run Code Metrics
        run: dart run bin/metrics.dart --reporter=github lib

Это позволит получить отчеты в таком формате:

Подробную информацию про все типы метрик и способы конфигурации можно посмотреть в документации.Как подключитьЕсли вы хотите попробовать пакет у себя, то вот краткий гайд о том, как его подключить в виде плагина для дартового анализатора.Шаг 1: установите пакет как dev-зависимость.

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

ИЛИДобавьте пакет вручную в pubspec.yaml. Важно: если ваш пакет еще не переведен на null safety, используйте версию 2.4.1.

dev_dependencies:
dart_code_metrics: ^3.0.0

Запустите команду установки зависимостей.

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

Шаг 2: добавьте конфигурацию в 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

В этой конфигурации указаны антипаттерны long-method и long-parameter-list, метрики с их пороговыми значениями и правила. Весь доступный список метрик можно посмотреть здесь, а список правил — здесь.Шаг 3: перезагрузите IDE, чтобы анализатор смог обнаружить плагин.Если вы хотите использовать пакет как CLI, то с документацией по использованию можно ознакомиться здесь.ЗаключениеУчитывая популярность Flutter, мы думаем над тем, какие метрики и правила могли бы помочь разработчикам на этом фреймворке. При этом мы открыты к предложениями: если у вас есть идеи правил или метрик, которые могли бы быть полезны разработчикам, пишущим на Dart или Flutter, смело пишите нам или оставляйте issue на GitHub. Мы будем рады добавить их и сделать жизнь разработчиков еще лучше.Наши планы на будущее всегда можно увидеть в публичном репозитории проекта в списке issue или в проектах, там же вы можете оставить обратную связь по инструменту.
===========
Источник:
habr.com
===========
Похожие новости:

Теги для поиска: #_open_source, #_programmirovanie (Программирование), #_dart, #_flutter, #_dart, #_linter, #_flutter, #_staticanalysis, #_codequality, #_linter (линтер), #_analizator_koda (анализатор кода), #_blog_kompanii_wrike (
Блог компании Wrike
), #_open_source, #_programmirovanie (
Программирование
), #_dart, #_flutter

Профиль ЛС

Ответить на тему

Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы

Текущее время: 22-Ноя 06:25
Часовой пояс: UTC + 5