fbpx

Comment Lint

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

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

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

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

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

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

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

Цели

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

Приземление

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

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

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

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

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

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

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

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

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

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

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

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

Установка

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

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

Виртуальный барбер

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

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