🏆 Рейтинг ІТ-работодателей 2019: уже собрано более 5000 анкет. Оцените свою компанию!
×Закрыть

DOU Проектор: Codecrumbs — новый взгляд на изучение и документирование исходного кода

В рубрике DOU Проектор специалисты рассказывают о том, как создавали свой продукт (как стартап, так и ламповый pet-проект).

Привет! Меня зовут Богдан, я работаю 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-репозиторий тут. Спасибо!

LinkedIn

4 комментария

Подписаться на комментарииОтписаться от комментариев Комментарии могут оставлять только пользователи с подтвержденными аккаунтами.
Изучаю исходный код (JavaScript и не только) уже почти 10 лет

Это вынужденность или реально нравится?

Одна из самых интересных профильных статей за последнее время. Обязательно попробую.

Выглядит перспективно. Спасибо!

Подписаться на комментарии