Каждый, кто пишет код, знает, что лучший код — это код, который не написан! Но как говорится, все не совершенны и нам приходится писать код. Но вот как помочь улучшить код, а затем следить за качеством кода, в вашем проекте? Этим вопросом постоянно задаются люди, которым не безразлично качество кода. Сейчас, на рынке много разных OSS решений для анализа качества кода, но в этом блог посте, я расскажу об интеграции бесплатного и очень удобного инструмента! Встречайте Code Climate!
Так как я пишу код в VSCode с использованием Remote-Containers, значит я расскажу о том, как связать эти отличные инструменты воедино и получить от этого пользу.
Немного предыстории, как я пришел к этому?
Ну вот значит, пишу я и пишу код, линтер работает, вроде все ок, думаешь “ну да, в моем коде есть недостатки, я их попозже поправлю” и это немного успокаивает. Но в голове крутятся вопросы:
- Насколько сложно понять код? Cognitive Complexity
- Насколько запутана логика ветвления условий? Cyclomatic Complexity
- Какое кол-во дублирующегося кода? Duplication
- Насколько хорошо можно поддерживать мой код? Maintainability
Я начал искать в интернете текущие решения, но по старой памяти, вспомнил про codeclimate и решил его попробовать. Добавил свой OSS проект в codeclimate дашборду.
Ну и результат не заставил ждать, и репо получил маркер “C” (он желтенький) так как у меня было 17 мест с дублированием кода и 2 места с кода с душком. Вообще имеются следующие маркеры, в порядке убывания качества кода - A, B, C, D, F.
Из каких шагов состоит билд процесс на codeclimate.com?
- Производится клонирование репо
- Валидация вашего .codeclimate.yml (если он будет обнаружен в корне вашего проекта). У меня такового нет, меня устраивает дефолтные проверки.
- Запуск команд из вашего .codeclimate.yml в prepare блоке.
- Скачивание образов инструментов анализа по умолчанию или же из вашего конфига
- Запуск каждого из инструментов анализа, в данном случае по умолчанию задействуются два образа structure и duplication.
Ну а далее отчет и их мега клевая метрика, которая и выставляет вашему проекту одну из букв, обозначающую качество кода.
Что удивило?
Очень удивило что по каждой найденной проблеме, ребята высчитывают время, необходимое для исправления. Это прям очень круто! И кстати букву качества они высчитывают именно исходя из суммарного времени на исправление проблем. Таким образом в проекте с большим количеством строк кода, эти цифры могут расти, а буква качества уменьшаться в сторону F. Так что чем раньше вы подключите этот сервис, тем быстрее начнете исправлять ситуацию, не доводя ее до абсурда, когда останется все выбросить и написать заново.
Как добавить значок codeclimate в ваш репо?
Для перехода на эту страницу, вам надо перейти по следующему URL https://codeclimate.com/github/название_организации_или_ваш_ник/название_репо/badges
Или же перейти на страницу вашего репозитория на codeclimate -> Repo Settings -> Badges.
Основные параметры качества, которыми руководствуется codeclimate
- Churn — показатель качества, часто изменяемых файлов на протяжении времени.
- Cognitive Complexity — Когнитивная сложность — это мера того, насколько сложно понять единицу кода. В отличие от Cyclomatic Complexity, которая определяет, насколько сложным будет тестировать ваш код, Cognitive Complexity сообщает вам, насколько сложным будет ваш код для чтения и понимания. Теперь Code Climate может помочь вам определить, какие методы чрезмерно сложны для понимания, и предотвратить их внедрение в ваш код.
- Cyclomatic Complexity — Цикломатическая сложность, иногда называемая сложностью Мак Кейба, представляет собой число линейно независимых путей в исходном коде. Проще говоря — это «количество решений, которые должен принять данный блок кода».
- Duplication - Механизм дублирования Code Climate, по своей сути, использует довольно простой алгоритм, чтобы определить, какие части вашего кода дублируются. Во-первых, исходные файлы анализируются в абстрактных синтаксических деревьях (AST). AST состоят из узлов: каждый узел имеет тип (который может быть чем-то вроде «назначения переменной» или «оператор if») и набор значений (который может быть именем переменной или другим узлом AST, представляющим подвыражение ). Каждому узлу присваивается числовая масса, рассчитанная как количество подузлов плюс 1. При поиске дублирования каждый узел в каждом AST сравнивается с каждым другим узлом в проанализированных AST. Узлы имеют одинаковую структуру, если они имеют одинаковый тип друг с другом, и если все их подузлы также имеют одинаковую структуру. Узлы, имеющие одинаковую структуру, но разные значения (например, 2 узла «назначения переменных», присваивающие переменные с разными именами и типами), считаются «похожими». Узлы, имеющие одинаковую структуру, а также одинаковые значения, считаются «идентичными».
- Maintainability - (Ремонтопригодность) — это оценка технического долга в репо, на основе стандартизированной 10-балльной оценки дублирования, цикломатической сложности, когнитивной сложности и структурных проблем.
Какие языки поддерживаются?
Следующие языки поддерживаются:
- Ruby
- Python
- PHP
- JavaScript
- Java
- TypeScript
- GoLang
- Swift
- Scala
- Kotlin
- C#
Довольно внушительный список! Ребята молодцы! Все популярные языки тут представлены.
Сервис — это хорошо, но локальный анализ не помешает
Линтер для IDE был придуман чтобы помочь, а не карать. В этом же смысле, хочется чтобы у тебя был такой же помощник, но который бы мог подсказать твои проблемы в коде по структуре и дублированию.
Как известно такие проверки не просты и дороги по ресурсам и времени, они не могут запускаться также часто, как и линтер (фактически на лету). Так как для действительно хорошего анализа, нужно просмотреть не одну строку и не один файл, а весь проект.
И для этой цели есть возможность запустить codeclimate локально в докерах для вашего проекта.
Так как я разрабатываю в VSСode + Remote-Containers — это не составит труда.
Сервис codeclimate локально — это реально!
Далее, по шагам будет рассмотрен процесс запуска сервиса codeclimate локально в ансамбле с VSCode.
Подготовка
У codeclimate есть один недостаток — это образы инструментов structure и duplication.
Каждый из этих образов весит ~1.9 Гигабайта в сжатом виде и при распаковке занимают по 5 Гигов каждый. Сначала меня это испугало, но затем подумал, ведь это все переиспользуется и никаких моментов, кроме размера пугать не должно. Многие сетуют, что было бы круто разделить образа по языкам, но пока все инструменты анализа собраны воедино.
Так что для начала подумайте о свободном месте на жестком диске, чтобы с лихвой хватило и системе и вашему проекту и образам докера.
Для скачивания образов необходимо выполнить следующие команды, на вашей хост машине:
И не переживайте! Самое главное выполнять эти команды по очереди! Так как после скачивания первого образа codeclimate-structure вы скачаете 1,9 Гб (вы знаете, что докер он слоистый), а значит, при скачивании codeclimate-duplication у вас будут скачаны недостающие слои, что в целом будет занимать ~100–200 Мб, что очень приятно. В реалии получается вы не качаете 4 гигабайта из интернете, в всего ~2 Гб. Далее скачиваете codeclimate образ и на этом первый этап подготовки заканчивается.
Настройка папки .devcontainer
Нам нужно затронуть Dockerfile, так как понадобится поставить докер клиент в докер, а также добавить настройки в runArgs файла devcontainer.json
Начнем с .devcontainer/Dockerfile и добавим установку докер клиента:
Общий вид докер файла, после добавления шага для установки docker-ce, вы можете поглядеть тут.
Теперь нужно добавить доступ докер клиенту в нашем докере для разработки, к демону докера, что запущен на нашей хостовой машине. Делается это через проброс сокета в качестве volume из хост машины в докер VSCode, для разработки. Нужно добавить следующую настройку в runArgs - параметр файла .devcontainer/devcontainer.json.
Так же можно сразу указать переменную окружения CONTAINER_TIMEOUT_SECONDS=1800, так как это нужно для увеличения времени, в течении которого может работать любой из инструментов codeclimate.
Далее нужно указать команду по установке и настройке враппера codeclimate, после создания нашего контейнера VSCode.
Эти команды, необходимо выполнить после того как будет создан докер VSCode, так как при выполнении установки, нужен будет доступ к демону докера через сокеты, который не будет доступен на этапе сборки.
Полную версию .devcontainer/devcontainer.json, можно увидеть тут.
Установка codeclimate враппера внутрь контейнера
Для начала нужно написать команду, что поможет установить codeclimate враппер.
Я добавил папку scripts, в которой сложил все, что мне было необходимо.
В этой папке, присутствует скрипт для установки враппера:
Но перед тем как выполнить этот скрипт, нужны проверки того, что в системе присутствуют образы codeclimate, иначе процесс установки будет затянут на N минут или часов, в зависимости от скорости интернета. Так как еще раз напоминаю, что образы не маленькие ~2 Гб в целом.
Для этих целей был написан файл чекера наличия образов в системе и я использовал JavaScript.
Так же в этом скрипте производится проверка на то, что команда выполняется внутри докера. Среди множества способов проверок, что есть в интернете, использовал проверку на наличие файла /.dockerenv и это отлично работает.
В итоге в package.json была добавлена следующая команда:
Теперь можно использовать команду npm run codeclimate:install для установки враппера.
Ремарка: С самого начала, я хотел все сделать на JavaSсript, без использования sh файла, но проблема была с последней командой в setup.sh. Каким бы я способом ее не запускал, процесс просто зависал и никакого stdout не было. Использовал и exec и spawn, но ничего не получилось. В итоге сделал как проще.
Запуск анализа кода
Ну вот теперь мы подошли к самому главному, цели всей статьи — запуску анализа кода. При этом можно получить отчет в трех форматах: html, json, text. Самый удобный конечно же — это отчет в html, его можно сразу же просмотреть в браузере и увидеть проблемы визуально. Ну а остальные форматы уже предназначены для ваших кастомных инструментов.
Но для того, чтобы успешно запустить анализ кода внутри докер образа VSCode, нужно знать реальный путь к примонтированной в докер папки репозитория. Все дело в том, как построена работа codeclimate. А она держится на временных запусках образов с монтированием папок хост машины внутрь этих образов. Соответственно, пути внутри Docker образа VSCode не подойдут.
Для определения пути из системы, был написан следующий скрипт scripts/volumes/inspect.js:
Данный скрипт, проходится по всем запущенным контейнерам, так как используется “docker ps” и получает все Mounts параметры запущенных контейнеров. Далее фильтрует вывод по включению строки mad-fake-slack и находит json с описанием монтирования папок в докер, где в Source поле — находится реальный путь. И если находится путь папки монтирования, с упоминанием mad-fake-slack, то этот путь возвращается в stdout, при помощи console.log(). Если не находится, то скрипт завершает процесс с кодом 1, что должно прервать цепочку команд.
В итоге для запуска анализа получается вот такая вот команда:
В результате выполнения такой команды, будет создан html отчет в папке reports, которую я специально создал для складирования отчетов.
Удобные команды
Так как мне сразу захотелось сделать возможность получения отчетов в разных форматах, то были добавлены следующие команды:
Теперь благодаря команде codeclimate:analyze, вы можете указать переменную окружения REPORT_FORMAT=html или REPORT_FORMAT=text или REPORT_FORMAT=json, перед командой и получить вывод отчета в указанном формате.
REPORT_FORMAT=html npm run codeclimate:analyze # запуск анализа и вывод отчета в html формате в папку reports с названием в виде текущей даты и времени
REPORT_FORMAT=json npm run codeclimate:analyze # запуск анализа и вывод отчета в json формате в папку reports с названием в виде текущей даты и времени
REPORT_FORMAT=text npm run codeclimate:analyze # запуск анализа и вывод отчета в text формате в папку reports с названием в виде текущей даты и времени
Отчет в html формате
Отчет выглядит доступен по ссылке.
В отчете есть ссылки на пояснения, по каждой найденной проблеме, так что даже неискушенный человек, сможет понять и при желании исправить найденные проблем. Одним словом, отчет очень информативен.
Заключение
Вот таким образом, вы можете настроить локальный запуск анализа качества вашего кода. Если вы разрабатываете в докере с использованием VSCode, то это не будет для вас проблемой, а наоборот, поможет быть увереннее в соблюдении общепринятых мерок качества кода.
Спасибо за прочтение данной статьи! Все, о чем было описано в данной статье, я активно использую в OSS проекте mad-fake-slack.