30.03.2022 18:48
qertis 7 1800 Источник

Часто бывает, что у вас запутанные комментарии в проекте? Или вы хотите сделать свою документацию понятным другим разработчикам? Тогда эта статья для вас.

Предыстория

Проверка на качество текста в 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)


  1. tuxi
    30.03.2022 19:25
    #24218489
    +2

    Про проверку грамматики встроенными средствами, вот буквально вчера случилось :)
    image


  1. upagge
    30.03.2022 20:46
    #24218721

    Респект. Тоже думал плагин запилить по главреду, да все времени не было, ну и потом необходимость отпала.


  1. unsignedchar
    30.03.2022 23:20
    #24219123
    +1

    Открыл код, но увлекся чтением комментариев ;)


  1. oxff
    31.03.2022 04:11
    #24219477
    +1

    Лучшие комментарии - их отсутствие.

    Рекомендую почитать книгу Clean Code дяди Боба. После этого нужда в комментариях просто пропадёт сама собой, потому что ваш код начнёт комментировать сам себя и будет читаться как хорошая проза, по выражению автора :)


    1. MaM
      01.04.2022 07:25
      #24222407

      Ну конечно, а еше он говорит, что дебагеры не нужны и все TDD должно быть обмазанно. Напомните они там уже запилили Generics или снова оказалось, что рассуждать и делать разные веши?
      Кнут, к примеру, продвигал идею литературного программирования. Комментарии сушествуют не потому, что кода достаточно, а потому, что код избыточен или контекстуально не полон, понимать надо.


      1. oxff
        01.04.2022 16:28
        #24224171

        Ну он вообще любит поговорить :-) И это здорово, потому что очень многие его мысли достойны внимания.

        Я не могу припомнить ни одного философа, который не имел бы спорных утверждений. Но это не отменяет их главных идей. При их чтении наша задача состоит в том, чтобы отсеивать зёрна от плевел, используя критическое мышление.

        Дядя Боб представляет свой взгляд на проблему развития и сопроводжения крупных проектов и предлагает рабочие способы для того чтобы код проекта, как это часто случается, не превратился со временем в помойку к которой все боятся прикоснуться.

        Я много лет назад листал Clean Code и затем смотрел видео лекции дяди Боба, прочитанные им в универе, и нашёл их весьма здравыми. В результате мои подходы к дизайну модулей и стиль кодирования заметно улучшились.


      1. oxff
        01.04.2022 17:06
        #24224343

        Что касается комментариев в коде, то я могу проиллюстрировать это простым примером:

        // Check to see if the employee is eligible for full benefits
if (employee.flags && HOURLY_FLAG && employee.age > 65) {
  ...
}

        Отдельный метод с говорящим именем выглядит намного лучше. Нагромождение деталей реализации не отвлекает внимания от бизнес логики.

        if (employee.isEligibleForFullBenefits()) {
  ...
}