fbpx
Почему вашему бизнесу нужен Comment Lint

Comment Lint

//
1 минута чтения

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

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

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

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

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

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

Цели

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

Приземление

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

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

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

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

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

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

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

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

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

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

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

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

Установка

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

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

Предыдущая статья

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

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

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