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

У рубриці DOU Проектор всі бажаючі можуть презентувати свій продукт (як стартап, так і ламповий pet-проект). Якщо вам є про що розповісти — запрошуємо взяти участь. Якщо ні — можливо, серія надихне на створення власної made in Ukraine продукту. Питання і заявки на участь надсилайте на [email protected] .

Привіт! Мене звати , я працюю 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 пропонує більше функціоналу, ніж інші, так як тільки він використовує AST-парсер для обробки коду.

Подальші плани

Codecrumbs дозволяє вивчати, документувати та пояснювати кодову базу швидше. Крім того, функція «download/upload» дозволяє дуже легко поширювати результати дослідження коду. Кінцева мета — розмістити безліч таких «кейсів» на codecrumbs.io і отримати щось у стилі бібліотеки проектів «explained with Codecrumbs». Місце, де всі зможуть ділитися знаннями на прикладах реальних проектів.

More cool features coming soon, stay tuned! І так, натисніть «star» і «розкажіть друзям» :) GitHub-репозиторій тут . Спасибі!

Опубліковано: 05/03/19 @ 08:05
Розділ Різне

Рекомендуємо:

Ruby/Rails дайджест #27: другий реліз beta-версії Ruby on Rails 6, оновлення JRuby, огляд потенційних фіч в Ruby 2.7
Финстрип за Лютий 2019, інфо-сайти. Стагнація
Scala дайджест #9: результати дослідження мови, Scala 3, модель TensorFlow в Scala
Навчання без учителя – вбивця математичного моделювання?
Питання ФОПів закрите, працюємо над законом для креативних індустрій. Про зустріч президента й прем'єр єра з ІТ