Проверка комментариев с Comment Lint

Comment Lint Plugin
15 марта, 2022
2 минут(ы) чтения

Проверка на качество текстов в семействах продуктов IntelliJ IDEA очень скудная. В стандартной поставке она позволяет обнаруживать некоторые опечатки текста. К счастью, теперь есть плагин Comment Lint, который обнаруживает сложные проблемы комментариев: подсвечивая ошибки читаемости и чистоты текста.

Цель продукта

Делать документацию к проекту понятной для всех разработчиков.

Профилирование

Часто бывает, что у вас запутанные комментарии? Сложно понять, что имел в виду программист, когда писал этот комментарий в куске функции?

Увы, но программисты часто не умеют четко доносить свои мысли в виде текста. Я решил сделать инструмент, который сделает легкой и читаемой внутреннюю документацию.

Актуализация проблемы

Пишете ли вы комментарии в коде? Используете ли при этом русский язык? Сталкиваетесь ли вы с тем, что спустя несколько месяцев комментарии становятся нечитаемы даже вами?

Если вы есть «да» хотя бы на один вопрос, то Comment Lint ваш выбор.

Приземление

Приведу мой случай: я пришел в новый проект, который, конечно же, был без документации. Все, что мне дали — монолитный репозиторий с запутанным кодом, обильно перемешанный сложно читаемыми комментариями. И тем не менее, именно комментарии стали единственным быстрым способом понять, что происходит в коде.

А что пробовали?

Решить проблему читаемости проекта я пытался через внедрение строгих линтеров кода. Прежде я думал код должен говорить сам за себя. Но код, увы, не говорит языком бизнеса: продукт-менеджера или аналитика. Строгие линтеры лишь раздувают код еще сильнее и он становится менее читаемым.

Потом своей команде я давал наставление писать осмысленные комментарии к каждому коммиту, чтобы видеть историю требований через git blame. Но в проекте, где часто изменяются требования, коммиты начинают ложиться друг на друга из-за чего по истории гита становится тяжело ориентироваться и в итоге понять, почему код написан именно так.

Потом я требовал команды грамотно описывать документацию в JSdoc, особенно в разделе description. Вначале это казалось мне самым лучшим решением. Но я заметил, что качество самого текста остается формально неточным и избыточным, из-за чего новые программисты не понимают сам текст.

Совсем недавно я прочитал книгу «Пиши, сокращай» и понял, это как раз то, что нужно для написания качественной документации на естественном языке. Именно интеграция сервиса ГЛВРД вошла в ядро плагина.

Автоматическая проверкаСкорость исправленияНизкая стоимостьУдобство
Отдельный сотрудник для документации✔️
Веб форма ГЛВРД ✔️✔️
Comment Lint✔️✔️✔️✔️
С чем сравнивать Comment Lint

Оцифровка проблемы и результата

Написание плохого ТЗ программисту стоит несколько часов, которые он проведет на новых митингах, тратя время продуктового менеджера.

comment lint
Пример главреда

Писать качественную документацию дорого. Бизнес режет косты, не нанимает технического писателя, а продуктовые менеджеры не выделяют должного времени на задачу написания качественной документации. Текучка кадров еще быстрее превращает код в нечто непонятное: и когда уходят ведущие разработчики, проект без качественной документации можно считать мертвым, новые разработчики в нем не разберутся.

Продуктовые менеджеры могут в разы снизить такой сценарий, если заставят разработчиков писать комментарии во внутренней документации, которые будут проходить валидацию Comment Lint’ом.

Возможности

Плагин в фоновом режиме анализирует русские комментарии и предлагает варианты по их улучшению.

Презентация продукта

Стоимость

В демо режиме стоит ограничение на один запрос к сервису в минуту. Платная версия пока в разработке, ключ можно купить напрямую обратившись к сайту glvrd.ru.

Поддерживаемые продукты

  • IntelliJ IDEA 2021.3.2 и выше
  • PyCharm 2021.3.1 и выше
  • GoLand 2021.3.2 и выше
  • WebStorm 2021.3.1 и выше
  • AppCode 2021.3.1 и выше
  • DataSpell 2021.3.1 и выше
  • Rider 2021.3.2 и выше
  • CLion 2021.3.1 и выше
  • PhpStorm 2021.3.1 и выше
  • RubyMine 2021.3.1 и выше

Установка

Скачать плагин можно с официального реестра JetBrains.

comment lint setup
Интерфейс скачивания плагина

Отправляемся в настройки:

Idea -> Plugins -> Available.

Далее пишем в поиске Comment Lint. Выбираем плагин, устанавливаем его и соглашаемся на перезапуску.

Ссылки

Исходный код плагина под MIT лицензией доступен на гитхабе.

Денис Сергеевич Басковский

Философ, изобретатель и поэт.

Добавить комментарий Отменить ответ

Разбить файл на равные части
Предыдущая статья

Как разбить файл на несколько частей

hr
Следующая статья

HR от Басковского

Exit mobile version