Часто бывает, что у вас запутанные комментарии в проекте? Или вы хотите сделать свою документацию понятным другим разработчикам? Тогда эта статья для вас.
Предыстория
Проверка на качество текста в IntelliJ IDEA скудная. Она позволяет обнаруживать некоторые опечатки, но, в целом, не очень полезна. Плагин Grazie улучшает ситуацию, но только в орфографии и грамматике.
К счастью, теперь есть плагин Comment Lint. Он использует сервис Glvrd, который обнаруживает более сложные проблемы: подсвечивая ошибки читаемости и чистоты текста.
Возможности
Плагин работает в фоновом режиме, анализируя русские комментарии и предлагая варианты их улучшения.
Поддерживаемые продукты JetBrains
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 и выше
Android Studio build 213.6461 и выше
CLion 2021.3.1 и выше
PhpStorm 2021.3.1 и выше
DataGrip 2021.3.2 и выше
RubyMine 2021.3.1 и выше
Установка
Отправляемся в настройки Idea -> Plugins -> Available. Далее пишем в поиске Comment Lint. Выбираем, загружаем его и соглашаемся на перезапуску.
Цена
В демо режиме стоит ограничение на один запрос к сервису в минуту. Платная версия пока в разработке, ключ можно купить напрямую обратившись к сайту glvrd.ru.
Ссылки
Исходный код плагина доступен на гитхабе.
Установить плагин можно на Jetbrains Marketplace.
Комментарии (7)
upagge
30.03.2022 20:46Респект. Тоже думал плагин запилить по главреду, да все времени не было, ну и потом необходимость отпала.
oxff
31.03.2022 04:11+1Лучшие комментарии - их отсутствие.
Рекомендую почитать книгу Clean Code дяди Боба. После этого нужда в комментариях просто пропадёт сама собой, потому что ваш код начнёт комментировать сам себя и будет читаться как хорошая проза, по выражению автора :)
MaM
01.04.2022 07:25Ну конечно, а еше он говорит, что дебагеры не нужны и все TDD должно быть обмазанно. Напомните они там уже запилили Generics или снова оказалось, что рассуждать и делать разные веши?
Кнут, к примеру, продвигал идею литературного программирования. Комментарии сушествуют не потому, что кода достаточно, а потому, что код избыточен или контекстуально не полон, понимать надо.oxff
01.04.2022 16:28Ну он вообще любит поговорить :-) И это здорово, потому что очень многие его мысли достойны внимания.
Я не могу припомнить ни одного философа, который не имел бы спорных утверждений. Но это не отменяет их главных идей. При их чтении наша задача состоит в том, чтобы отсеивать зёрна от плевел, используя критическое мышление.
Дядя Боб представляет свой взгляд на проблему развития и сопроводжения крупных проектов и предлагает рабочие способы для того чтобы код проекта, как это часто случается, не превратился со временем в помойку к которой все боятся прикоснуться.
Я много лет назад листал Clean Code и затем смотрел видео лекции дяди Боба, прочитанные им в универе, и нашёл их весьма здравыми. В результате мои подходы к дизайну модулей и стиль кодирования заметно улучшились.
oxff
01.04.2022 17:06Что касается комментариев в коде, то я могу проиллюстрировать это простым примером:
// Check to see if the employee is eligible for full benefits if (employee.flags && HOURLY_FLAG && employee.age > 65) { ... }Отдельный метод с говорящим именем выглядит намного лучше. Нагромождение деталей реализации не отвлекает внимания от бизнес логики.
if (employee.isEligibleForFullBenefits()) { ... }
tuxi