I regret to report that I've just recently looked again at my programs for prime factors and tic-tac-toe, and they are entirely free of any sort of comments or documentation.
— Donald E. Knuth
Каждый программист не раз сталкивался с ситуацией, когда приходится читать чужой код не имея представления для чего нужна та или иная функция, класс и как оно вообще все взаимосвязано.
Такое случается даже со своими программами и скриптами, написанными на write-only ЯП.
Разработчики, имеющие дар работать с таким кодом высоко ценятся в коллективе.
Такое чудо-лабиринты из кода бывают, когда исходный код имеет:
- Непоследовательный стиль разработки
- Чересчур сложную и запутанную структуру программы
- Очевидные логические ошибки или упущения
- Запущенность
Надо понимать, что существует большое отличие между живым рабочим кодом и неким учебно образовательным. В первом случае на процесс разработки может влиять целый ряд технических, коммерческих и даже бытовых причин. Под их воздействием даже самый строгий и элегантный дизайн ПО может превратиться в спагетти. Основные причины таких метаморфозов знакомы многим программистам.
- Самое первое и основное требование к рабочей программе то, что она должна исполняться здесь и сейчас, часто на различных устройствах и платформах. Если нужно придумать странные обходные решения из-за ограничений, накладываемых доменными политиками, то эти решения обязательно будут придуманы и реализованы.
- Разработка ПО для AppleStore, пример с Wireguard довольно показателен.
- Желание использовать наиболее производительные и эффективные вычислительные алгоритмы. Сравните сколько строчек кода в тренировочной программе нахождения простых чисел и той, что используется в промышленной среде.
- Требования безопасности и устойчивости к пользовательским ошибкам ввода данных приводят к многочисленным ветвлениям с проверками границ и длины массивов, типов данных и разных регистров рабочей памяти.
- В коммерческих приложениях довольно часто можно встретить обфусцированный PHP, или JavaScript.
Рис. 1 Exploits of a mom.
Герменевтика исходного кода требует особых навыков и инструментов. Навыки такого рода приходят лишь с опытом, однако доскональное знание синтаксических особенностей языка и сопутствующей документации могут облегчить дело тем, кому не хватает практического опыта. Другим таким подспорьем являются специальные инструменты исследования исходного кода.
Sourcetrail на помощь
Приложение Sourcetrail представляет собой продвинутый интерактивный проводники и анализатор, который позволяет активно исследовать исходный код, индексируя и собирая данные о его структуре. Интерфейс приложения включает в себя три основные части.
Рис. 2 интерфейс Sourcetrail.
- Быстрый поиск и выбор индексированных символов в исходном коде. Окно автозаполнения мгновенно предоставит обзор всех совпадающих результатов по всей кодовой базе. Поддерживается нечеткий поиск.
- Граф отображает структуру исходного кода. В фокусе находится текущий выбранный символ, на схеме явно указаны входящие и исходящие зависимости от других символов.
- В представлении Код в виде списка отображаются все фрагменты исходного кода для текущего выбранного символа.
При запуске Sourcetrail предлагает выбрать проект. В комплекте несколько учебно-тренировочных для всех поддерживаемых ЯП. После выбора проекта Sourcetrail индексирует исходный код и затем можно начинать работу с проектом.
Рис. 3 выбор проекта.
Структуры и классы отображаются курсивом; пакеты, модули и пространства имен — розоватым цветом; функции и методы — желтым цветом, а переменные и области — голубым. В данный момент реализована поддержка следующих языков программирования:
- C/C++;
- Java;
- Python.
Рис. 4 метод Run.
Мы выбрали проект tictactoe_cpp и затем метод Run. С помощью графа наглядно можно увидеть, что Run вызывается единожды из функции main. Помимо вершин графа, также и ребра несут полезную смысловую нагрузку.
- Включение текста из файла: зеленое → зеленое.
- Использует тип: желтое → серое.
- Использование переменной: желтое → голубое.
- Вызов функции: желтое → желтое.
Рис 5 обозначения ребер графа.
Кроме того существуют определения для переопределения (слева) и наследования метода (справа).
Рис 6 обозначения ребер для переопределения и наследования метода.
Sourcetrail всячески стремится реализовать интерактивное поведение. При выборе объектов графа в представлении кода автоматически подсвечиваются соответствующие символы. Обратное также верно, выбор символов в представлении кода приводит к автоматической перенастройке графа. Выбранный на графе элемент сразу же переходит в центр, также обновляется содержимое в панели кода. При наведении курсора на объекты графа соответствующие символы выделяются прямоугольной рамкой. И снова обратное верно для наведения курсора на символы в панели кода.
Можно задавать уровень детализации и глубины построения графа с помощью trail controls в левом верхнем углу.
Рис. 7 настройки отображения графа.
Интересной, для подобного класса приложений, концепцией пользовательского интерфейса является навигация в стиле веб-браузера. На Рис. 2 видны кнопки Назад, Вперед и Дом. Надо сказать — действительно удобно. Кнопка Обновить не перерисовывает граф, как можно было бы предположить, а предлагает заново индексировать файлы исходного кода. Кнопка Закладки позволяет добавить символ в избранные.
Одним из инструментов trail controls является custom trail, в самом верху. Вызвав соответствующую форму, можно выбрать необходимые составные графа, детализацию, отправной и целевой узел и тип построения.
Рис. 8 Построение графа с custom trail.
Установка Sourcetrail
Дистрибутив приложения Sourcetrail доступен для ОС Windows, macOS и Linux. Пользователи Windows как обычно запускают setup.exe, для macOS установка проходит штатными средствами операционной системы. Для Linux существует два варианта:
- скачать пакет .tar.gz и затем запустить команду Sourcetrail.sh;
- загрузить образ AppImage, дать права на исполнение с помощью chmod + x filename и затем просто запустить его.
Настройки будут хранится в следующих местах.
- Windows
- macOS ~/Library/Application Support/Sourcetrail;
- Linux ~/.config/sourcetrail.
Текущая версия Sourcetrail требует установки среды выполнения Java 8 для индексации Java проектов. Бинарная архитектура Sourcetrail, должна соответствовать таковой для JRE. Для Sourcetrail 32-бит нужна 32-бит JRE, а для 64-бит версии приложения — соответственно 64-бит JRE.
Поддержка сторонних IDE и редакторов
Sourcetrail поддерживает интеграцию с целым рядом IDE и текстовых редакторов. Все плагины идут с открытым исходным кодом, разработка ведется на github.
- Atom;
- CLion;
- Eclipse;
- Emacs;
- IntelliJ IDEA;
- Qt Creator;
- Sublime Text;
- Vim;
- Visual Studio Code.
Возможности CLI
С помощью командной строки можно индексировать, или настроить проект в Sourcetrail.
sourcetrail index [options...] projectfile
Возможные options:
--help;
--version;
--project-file #путь к .srctrlprj файлу.
Настройка проекта:
sourcetrail config [options...]
--help;
--indexer-threads #количество потоков индексирования;
--use-processes #включить, или выключить индексирование C/C++ в разных процессах;
--logging-enabled #включить/выключить логирование в файл / на терминал;
--verbose-indexer-logging-enabled #не стоит злоупотреблять, тормозит индексирование;
--jvm-path;
--jvm-max-memory;
--maven-path #путь к бинарникам maven;
--jre-system-library-paths #путь к jar файлам системной JRE;
--global-header-search-paths;
--global-framework-search-paths;
--show #показать настройки и значения;
Резюме
Бытует мнение, что разработчики тратят большую часть времени на то, чтобы осмыслить существующий код, нежели на написание нового. Такие средства анализа исходного кода, как Sourcetrail могут существенно сместить баланс в пользу последнего, без потери качества. Хочется отметить фокус на продуманный и знакомый динамичный пользовательский интерфейс, который отлично выполняет роль ненавязчивого помощника и существенно экономит время на рутинных процедурах.
