DOU Проектор: Codecrumbs — новый взгляд на изучение и документирование исходного кода
В рубрике DOU Проектор все желающие могут презентовать свой продукт (как стартап, так и ламповый pet-проект). Если вам есть о чем рассказать — приглашаем поучаствовать. Если нет — возможно, серия вдохновит на создание собственного made in Ukraine продукта. Вопросы и заявки на участие присылайте на Данный адрес e-mail защищен от спам-ботов, Вам необходимо включить Javascript для его просмотра. .
Привет! Меня зовут Богдан, я работаю JavaScript программистом. Изучаю исходный код (JavaScript и не только) уже почти 10 лет. В этой статье я хочу рассказать свою историю разработки инструментов для анализа кода, а также представить свой последний Github-проект Codecrumbs. Он позволяет изучать, документировать и объяснять кодовую базу быстрее.
Идея
Всё началось ровно два года назад, когда я решил изучить исходный код React. Это оказалось довольно непростой задачей, и я провозился почти 3 месяца, пытаясь понять и построить в своей голове хоть какую-то картинку того, как всё работает. В итоге появился проект Under-the-hood-ReactJS. По отзывам сообщества, его можно считать «успешным», но уже тогда было понятно, что мой процесс изучения исходного кода был крайне неэффективным. Взять хотя бы рисование блок-схем: я описывал логику вручную, через flow-charts, и каждый раз, когда находил что-то новое в коде, — вынужден был перерисовывать схему. Нужно было это автоматизировать. В итоге появился проект js-code-to-svg-flowchart — библиотека, которая генерирует блок-схему по исходному коду. Уже лучше, но не совсем то, что мне было нужно.
Анализируя собственный опыт изучения исходного кода больших проектов, я пришел к выводу: мне не так сложно понять кусок кода какой-то конкретной функции, как тяжело увидеть «big picture», наложить абстракции и отсеять неважные детали. Каждый раз я ловил себя на мысли, что я начинаю бессмысленно прыгать между файлами, зачастую открывая один и тот же файл несколько раз и осознавая, что «ой, я это уже видел, это не то место» или «где же то нужное место, которое я только что видел». Итак, мне нужен был какой-то инструмент, чтобы помечать важные места в коде, и в идеале, чтобы он строил ту самую «визуальную картинку» того, как все работает. Также он должен работать с существующими кодовыми базами без необходимости переписывать код для каждого «нового фреймворка». Так появился проект Codecrumbs (название производное от «code» и «breadcrumb») — инструмент, который позволяет оставлять «хлебные крошки» в коде и по ним строить визуальную схему.
Реализация проекта
Проект является классическим примером клиент-серверной архитектуры с общением через сокеты. Всё реализовано средствами JavaScript. Сервер анализирует код проекта и ищет комментарии, содержащие «codecrumbs», собирает их и отправляет на клиент. Клиент накладывает их на структуру проекта и рисует SVG картинку. Есть поддержка «live updates», так что процесс использования может быть следующим: на одном мониторе ваш редактор кода, на другом — вкладка браузера с Codecrumbs-клиентом. Пишете комментарий — схема перестраивается на лету.
Давайте рассмотрим основные фичи.
Trail of breadcrumbs («цепочка крошек») — последовательность крошек, которые описывают какой-то сценарий внутри приложения (например, аутентификация или отправка формы на сервер и т. д.).
Dependencies tree («дерево зависимостей») — позволяет легко определять, «что куда импортируется».
Flowchart («блок-схема») — позволяет посмотреть блок-схему выбранного файла.
Кроме этого, просто запустив Codecrumbs для нескольких проектов одновременно, можно изучить, как они интегрируются между собой.
После всего этого также можно скачать и «отправить другу» схему, которую вы только что изучили. Воспользуйтесь функцией «download», чтобы получить текущее состояние приложения в формате json-файла. Файл будет содержать минимальное количество данных, чтобы отобразить схему: для этого не обязательно иметь локально тот же исходный код — Codecrumbs может работать в «standalone» режиме в браузере. Пример тут.
Поддержка языков. В текущей версии поддерживаются следующие языки программирования:
- JavaScript;
- TypeScript;
- Python;
- PHP;
- Java;
- C++.
JavaScript предлагает больше функционала, чем остальные, так как только он использует AST-парсер для обработки кода.
Дальнейшие планы
Codecrumbs позволяет изучать, документировать и объяснять кодовую базу быстрее. Кроме того, функция «download/upload» позволяет очень легко распространять результаты исследования кода. Конечная цель — разместить множество таких «кейсов» на codecrumbs.io и получить что-то в стиле библиотеки проектов «explained with Codecrumbs». Место, где все смогут делиться знаниями на примерах реальных проектов.
More cool features coming soon, stay tuned! И да, нажмите «star» и «расскажите друзьям» :) GitHub-репозиторий тут. Спасибо!
