Проверка на качество текстов в семействах продуктов IntelliJ IDEA очень скудная. В стандартной поставке она позволяет обнаруживать некоторые опечатки текста. К счастью, теперь есть плагин Comment Lint, который обнаруживает сложные проблемы комментариев: подсвечивая ошибки читаемости и чистоты текста.
Цель продукта
Делать документацию к проекту понятной для всех разработчиков.
Профилирование
Часто бывает, что у вас запутанные комментарии? Сложно понять, что имел в виду программист, когда писал этот комментарий в куске функции?
Увы, но программисты часто не умеют четко доносить свои мысли в виде текста. Я решил сделать инструмент, который сделает легкой и читаемой внутреннюю документацию.
Актуализация проблемы
Пишете ли вы комментарии в коде? Используете ли при этом русский язык? Сталкиваетесь ли вы с тем, что спустя несколько месяцев комментарии становятся нечитаемы даже вами?
Если вы есть «да» хотя бы на один вопрос, то Comment Lint ваш выбор.
Приземление
Приведу мой случай: я пришел в новый проект, который, конечно же, был без документации. Все, что мне дали — монолитный репозиторий с запутанным кодом, обильно перемешанный сложно читаемыми комментариями. И тем не менее, именно комментарии стали единственным быстрым способом понять, что происходит в коде.
А что пробовали?
Решить проблему читаемости проекта я пытался через внедрение строгих линтеров кода. Прежде я думал код должен говорить сам за себя. Но код, увы, не говорит языком бизнеса: продукт-менеджера или аналитика. Строгие линтеры лишь раздувают код еще сильнее и он становится менее читаемым.
Потом своей команде я давал наставление писать осмысленные комментарии к каждому коммиту, чтобы видеть историю требований через git blame. Но в проекте, где часто изменяются требования, коммиты начинают ложиться друг на друга из-за чего по истории гита становится тяжело ориентироваться и в итоге понять, почему код написан именно так.
Потом я требовал команды грамотно описывать документацию в JSdoc, особенно в разделе description. Вначале это казалось мне самым лучшим решением. Но я заметил, что качество самого текста остается формально неточным и избыточным, из-за чего новые программисты не понимают сам текст.
Совсем недавно я прочитал книгу «Пиши, сокращай» и понял, это как раз то, что нужно для написания качественной документации на естественном языке. Именно интеграция сервиса ГЛВРД вошла в ядро плагина.
| Автоматическая проверка | Скорость исправления | Низкая стоимость | Удобство | |
|---|---|---|---|---|
| Отдельный сотрудник для документации | ❌ | ❌ | ❌ | ✔️ |
| Веб форма ГЛВРД | ❌ | ✔️ | ✔️ | ❌ |
| 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.
Отправляемся в настройки:
Idea -> Plugins -> Available.
Далее пишем в поиске Comment Lint. Выбираем плагин, устанавливаем его и соглашаемся на перезапуску.
Ссылки
Исходный код плагина под MIT лицензией доступен на гитхабе.
