Новый взгляд на изучение и документирование исходного кода

    TL;DR Привет. Меня зовут Богдан и я изучаю проблемы чтения кода. Я только что закочнил первую рабочую версию «codecrumbs» — визуального инструмента для изучения исходного кода с помощью «хлебных крошек». Гитхаб репозиторий можно посмотреть тут.

    image

    Проблема


    Недавно я проводил опрос о главных проблемах с которыми мы сталкиваемся когда начинаем изучать исходный код большого проекта (если вы ещё не участвовали, то пройти опрос всё ещё можно тут).

    Главный вопрос который меня интересовал: что именно в изучении кода нового для вас проекта самое сложное? Посмотрим на тренд ответов на картинке ниже.

    image

    Как, собственно, и предполагалось, намного сложнее соединить все точки в единую картинку, чем понять, что делает код внутри конкретной функции или файла (как ни странно, редакторы кода уделяют намного больше внимания именно «одному файлу», а не «картинке в целом»). Проблема в том, что когда мы первый раз открываем код проекта, на нас за один раз сваливается слишком много информации. Мы начинаем бессмысленно прыгать между файлами, в полном хаосе, зачастую открывая один и тот же файл несколько раз, осознавая, что “ой, я это уже видел, это не то место” или “где же то нужное место, которое я только что видел” и впустую тратя время. Итак, нам определенно нужен какой-то инструмент чтобы отмечать важные места в коде и, в идеале, чтобы он строил ту самую “общую визуальную картинку” того, как все работает.

    Codecrumbs спешит на помощь


    Codecrumbs (название производное от “code” и “breadcrumb”) — инструмент, что позволяет оставлять “хлебные крошки” в коде и по ним строить визуальную схему.

    Как это работает? Вы выполняете команду codecrumbs указав пути к коду проекта, codecrumbs анализирует исходный код и создает его визуальное представление. Добавьте codecrumb-коимментарий и обновленное состояние кодовой базы отобразится в визуальном клиенте в браузере на лету.

    Основные возможности


    Trail of breadcrumbs («цепочка крошек») — последовательность крошек, которые описывают какой-то сценарий внутри приложения (например, аутентификация или отправка формы на сервер и т. д.).

    image

    Dependencies tree (“дерево зависимостей”) — позволяет легко определять “что куда импортируется”.

    image

    Flowchart (“блок-схема“) — позволяет посмотреть блок-схему выбранного файла.

    image

    Кроме этого, просто запустив “codecrumbs” для нескольких проектов одновременно можно изучить их интеграцию между собой.

    image

    После всего этого также можно скачать и “отправить другу” схему, которую вы только что изучили. Воспользуйтесь функцией “download” чтобы получить текущее состояние приложения в формате json файла. Файл будет содержать минимальное количество данных для отображения схемы. Для этого не обязательно иметь локально тот же исходный код — “codecrumbs” может работать в “standalone” режиме в браузере. Пример тут.

    image

    Поддержка языков. В текущей версии поддерживаются следующие языки программирования:

    • JavaScript
    • TypeScript
    • Python
    • PHP
    • Java
    • C++

    JavaScript предлагает больше функционала чем остальные, так как только он использует AST-парсер для обработки кода.

    Дальнейшие планы


    Данный инструмент (codecrumbs) позволяет изучать, документировать и объяснять кодовую базу быстрее. Кроме того, функция “download/upload” позволяет очень легко распространять результаты исследования кода. Конечная цель — разместить множество таких “кейсов” на https://codecrumbs.io и получить что-то в стиле библиотеки проектов «Explained with codecrumbs» — место, где все смогут делиться знаниями на примерах реальных проектов.

    More cool features coming soon, stay tuned! И да, нажмите “star” и расскажите друзьям :) Github-репозиторий тут github.com/Bogdan-Lyashenko/codecrumbs. Спасибо!
    Поделиться публикацией

    Похожие публикации

    Комментарии 35

      +2
      Смотрю на сайт и вообще не понимаю как зааплоадить свой проект туда. Хочу пихнуть туда проект на 20 мегабайт и 4 тыс классов
        +1
        Сначала нужно запустить codecrumbs локально для вашего проекта, экспортировать стор, который уже потом можно зааплоадить на сайт (в виде json файла).
        –2
        Посмотрим на тренд ответов на картинке ниже
        Откуда опрос? Кто отвечал? Дайте пожалуйста ссылку и, если источник не на русском, краткую сводку (tl;dr) о чем там.
        Trail of breadcrumbs («цепочка крошек»)
        Я так понимаю, это ключевая особенность вашего проекта, остальное (flow chart и представление зависимостей) скорее всего уже много раз сделаны, причем я сильно сомневаюсь в полезности любого из них, хотя я — это ленивый C# десктоп программер с мощнейшим IDE в виде Visual Studio+Intellisense, веб-дизайнеры, видимо, довольствуются чем-то сильно попроще.

        Почему главной особенности отведен всего один абзац и один анимированный гиф? Неужели все так плохо, что даже попиарится (показать и доказать, что красиво и полезно) стыдно?
        Новый взгляд на изучение и документирование исходного кода
        В каком месте новый? Где стало лучше? По сравнению с чем сравнивали?
          –1
          ну, не у всех есть деньги на PHPStorm какой-нибудь. Я вот сижу на VS Code, да и много кто в Sublime, VS Code, Notepad++, Atom или еще чем сидит
            +4
            Это шутка такая? У программиста, даже начинающего, нет возможности выделять 600 рублей в месяц на IDE для комфортной работы?
              0
              у меня нет, например. Потому что из всего того функционала, по факту, только поддержка нормальной документации нужна. В VSCode с этим пока не очень — phpDoc блоки читает 100% внутри одного класса\файла, из других — через раз. Вот я не просто начинающий — студент, который работает в маке и пишет диплом. С мака дохода мало — работаю мало потому что. И денег на продукт, большей частью которого пользоваться не буду — выделять не хочется и не можется.
                0
                студент

                На всякий случай (возможно есть какие-то ограния): есть студенческая лицензия.

                  0
                  так то так, но у рядового колледжа, вроде моего МГОК участия в системе, по которой они лицензии дают, не имеется. Перепроверил — не работает. Либо мыло аккредитованного универа, либо гитхаб акк с каким то паком для студентов. Крч либо пиратить, либо не юзать
          +4
          А где посмореть крошки самого проекта крошек?
            +1
            Хаха, да, у меня была такая же идея «Codecrumbs project explained with codecrumbs» :) (сделаю позже)
              +3
              Это мне кажется довольно логичным заключением. И было бы неплохо добавить примеров как это использовать в не-js проектах.
            0
            Интересно.
            А не думали сделать это в виде расширения к Sourcegraph?
            Не знаю возможно ли это, т.к. никогда не делал для него расширения, но он сейчас очень популярен и, возможно, это поможет популяризировать ваш проект.
              0

              Зачем что-то куда-то загружать для визуализации? Почему не сделать это внутри редактора/IDE?

                0
                Как написано в Readme, не нужно загружать ничего
                How it works? You run codecrumbs command for a codebase, it analyzes source code and builds its visual representation. Write down a codecrumb-comment and codebase state will be reflected by visual client in browser on the fly.
                  0
                  visual client in browser
                +3
                Подобного приложения не хватает для визуализации использования бюджета.
                  +1
                  Благодарю вас за такой труд. Выскажу некоторые пожелания.
                  … позволяет легко определять “что куда импортируется”
                  В этом блоке у вас получается сразу довольно сложная схема.
                  Она может быть как-то упрощена или отфильтрована?
                  Блок-схему выбранного файла.
                  — очень хорошо, полезно.

                  можно изучить их интеграцию между собой.
                  Тут также, если это UML диаграммы, то можно ли будет их как-то отфильтровать, так чтобы сразу не выводить такую сложную схему. А как-то её упростить. С возможностью не выводить всю схему. С возможность скрыть/показать определенные связи.

                  Вы делаете полезный инструмент. Благодарю за публикацию.
                    0

                    Спасибо, пометил таски себе в беклог)

                    +1

                    Очень интересная мысль именно строить цепочки зависимостей функций по бизнесовым кейсам. Прям востребованная. Вопрос только в том — почему бы сразу нормально не писать код (т.е. каждая функциональность — отдельный эндпойнт, в остальном — попрыгаем между функциями). И может ли нам помочь технология типа opentracing/jaeger, т.к. логика может быть размазана и не только по коду, но и вообще разнородными модулями (например, бекендом на джава и хранимыми процедурами в БД).
                    В остальном — правда очень интересно, но хочется понять целевую аудиторию проектов (rest-сервисы? Gui-монолитные-приложения? Etc)

                      +1
                      Да хоть кто, это очень крутая штука. У меня есть идея написать подобное, но я смотрю больше в сторону компиляции, анализа оптимизаций, последовательности линковки и т.д. Сегодня качественные утилиты для анализа кода стали нужней, наверное, больше чем что-либо еще. Так как по сути это совсем слепая зона. Мы научились бороться с стилем, версионированием, документацией, рефакторингом, постепенно даже появляются унифицированные протоколы для расширения ide, но все еще не победили контроль сложности на самом высоком уровне абстракций.
                        +1
                        Не хватает подсчета цикломатической сложности кода )))
                        В остальном — +1
                      0

                      Мой основной посыл наверное был решить проблему когда приходишь на «уже написанный существующий проект». Обычно там «все плохо», и большим успехом уже будет хотябы понять тот код, желательно быстро)

                      0
                      Выглядит прикольно! А планируете добавить Go?
                        0

                        Поддержка Go присутствует:)
                        (fallback parser подхватит)

                        0
                        JavaScript предлагает больше функционала чем остальные, так как только он использует AST-парсер для обработки кода.

                        Планируется ли поддержка TypeScript?

                          0
                          Dependencies tree и Flowchart (которые как раз работают только для JavaScript) требуют AST parser. Я использую babel-parse для этого, который поддерживает TypeScript, но не всегда последнюю версию (чаще как раз не последнюю), в этом собственно проблема. Обычно на проектах с TypeScript-ом используется нативный TypeScript компилятор, а не babel, поэтому я не могу быть уверен что он не свалится :)
                          –2
                          Хм. Я правильно понимаю, что Вы сделали своеобразный аналог DRAKON Editor?)
                            0
                            Очень полезный проект. Хотелось бы видеть поддержку C#
                              0

                              Должно работать с C# «из коробки»

                              +1
                              О, это очень здорово! Хотелось бы поинтересоватся не думали ли вы подготовить представление пулл реквеста в подобной форме для code review. Бывает очень сложно понять что вообще происходит с кодом глобально особенно если на ревью большой кусок кода.
                              Основная проблема, во всяком случае случющейся у нас, это оценить как код соотностися с общей архетектурой проекта.
                                0
                                Очень хорошая идея, добавил в бэклог, спасибо.
                                –2
                                UML? — не, не слышали.
                                  0
                                  эхх! а я лет 10 тому назад парсил код и использовал www.graphviz.org
                                  Т.к. технологии делают новый виток, надо попробовать перепилить это на WebGL.
                                    0
                                    Проблема с инструментами типа graphviz и т.п. что они строят очень абстрактную документацию не привязанную к коду — то есть можно понять общую идею, но пофиксить баг в фиче это никак не поможет :)

                                  Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                                  Самое читаемое