Аннотировать исходный код с диаграммами в качестве комментариев

Я пишу много кода (прежде всего с ++ и javascript), который затрагивает вычислительную геометрию и графику и подобные темы, поэтому я обнаружил, что визуальные диаграммы являются неотъемлемой частью процесса решения проблем.

Я только что определил, что «о, не было бы просто замечательно, если бы я мог как-то прикрепить нарисованную от руки диаграмму к коду кода в качестве комментария», и это позволило бы мне вернуться к тому, над чем я работал, дни, недели, месяцы раньше и гораздо быстрее меняют мои алгоритмы.

Как визуальный ученик, я чувствую, что у этого есть потенциал, чтобы улучшить мою производительность почти с каждым типом программирования, потому что простые диаграммы могут помочь с пониманием и рассуждением о любом типе нетривиальной структуры данных. Графики например. Во время занятий теорией графов в университете я только мог по-настоящему понять отношения графа, которые я мог нарисовать схематически.

Так...

Нет IDE, насколько мне известно, позволяет сохранить изображение в качестве комментария к коду.

Я думал, что я или кто-то еще мог бы придумать какой-нибудь достаточно простой в использовании инструмент, который может конвертировать изображение в двоичную строку base64, которую я затем могу вставить в свой код.

Если процесс преобразования / вставки может быть достаточно упорядочен, это позволит значительно улучшить связь между диаграммой и реальным кодом, поэтому мне больше не нужно выполнять хронографический поиск по моим блокнотам. Еще более круто: плагины для IDE для автоматического разбора и отображения изображения. В этом нет ничего сложного с теоретической точки зрения.

Я предполагаю, что мне потребовалось бы дополнительное время, чтобы на самом деле понять, как расширить мои любимые IDE и поддерживать эти плагины, так что я был бы полностью доволен своего рода постпроцессором кода, который выполнял бы такой же анализ и рендеринг изображений и показывать их рядом с кодом, внутри браузера или что-то еще. Так как я по профессии программист javascript.

Что думают люди? Кто-нибудь заплатит за это? Я буду. Но, возможно, я бы также отметил, что независимо от того, заплатил бы я или какое-то значительное количество моих коллег за такую ​​вещь, единственный способ добиться успеха такой вещи был бы через релиз с открытым исходным кодом.

А как насчет плагина Image Insertion для Visual Studio ?

Если вы используете другую среду IDE и либо она не поддерживает встроенные изображения, либо у вас нет времени на ее расширение, то как насчет размещения ссылки на изображение в комментариях, в то время как изображение будет находиться где-то в хранилище? ?

Если вы не являетесь художником ASCII , вы можете использовать doxygen в качестве инструмента документации вместе с интегрированной в него точкой / графиком .

Это позволяет писать текстовые описания графиков и отображать их в документации.

Например, это описание:

digraph finite_state_machine {
    rankdir=LR;
    size="8,5"
    node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
    node [shape = circle];
    LR_0 -> LR_2 [ label = "SS(B)" ];
    LR_0 -> LR_1 [ label = "SS(S)" ];
    LR_1 -> LR_3 [ label = "S($end)" ];
    LR_2 -> LR_6 [ label = "SS(b)" ];
    LR_2 -> LR_5 [ label = "SS(a)" ];
    LR_2 -> LR_4 [ label = "S(A)" ];
    LR_5 -> LR_7 [ label = "S(b)" ];
    LR_5 -> LR_5 [ label = "S(a)" ];
    LR_6 -> LR_6 [ label = "S(b)" ];
    LR_6 -> LR_5 [ label = "S(a)" ];
    LR_7 -> LR_8 [ label = "S(b)" ];
    LR_7 -> LR_5 [ label = "S(a)" ];
    LR_8 -> LR_6 [ label = "S(b)" ];
    LR_8 -> LR_5 [ label = "S(a)" ];
}

отображается как:

Вы можете попробовать режим Emacs Artist. Это сделало бы ascii art, а не изображения как таковые, так что это может быть или не быть тем, что вы ищете. В частности, если ваша IDE не поддерживает шрифты фиксированной ширины, это не будет полезно. Будучи простым текстом, он будет очень хорошо играть с контролем версий.

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

Чтобы запустить режим Artist в Emacs, выполните Alt-x, введите Artist-Mode и нажмите Return. Средняя кнопка мыши вызывает меню. По умолчанию сочетания клавиш для вырезания и вставки не являются обычными окнами, но вы можете включить режим CUA, чтобы изменить это.

Что думают люди? Кто-нибудь заплатит за это? Я буду.

ZOMG, я подхожу к той же категории, что и вы, и хотел бы, чтобы такая функция была прямо в IDE.

На данный момент я просто склонен делать много "ASCII" искусства ", как это:

// ******************************************************
// *v3            |e5          v4*           |e6      v6*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |p1        *
// *              |            e1*-----------~----------*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *cen           |p0          v0*           |        v5*
// *--------------~--------------************************
// *e4            |              *           |e7        *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |p2        *
// *              |            e2*-----------~----------*
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *              |              *           |          *
// *v2            |e3          v1*           |e8      v7*
// ******************************************************

Основное значение, которое я нахожу, - видеть имена переменных, соответствующие визуальной диаграмме, особенно когда мы используем сложные обходы сеток и тому подобное для новых алгоритмов сетки. Этот трюк генерации doxygen графа, показанный в одном из ответов, очень крутой - я должен попробовать это больше.

Есть так много вещей, которые легче общаться визуально, даже не обязательно используя графики. Пример:

... или это (сравнение моего алгоритма, который я называю «подразделение крюка» со стандартным подразделением CC, как используется Pixar):

Это дало бы коду столько контекста, чтобы просто увидеть, что делают эти операции и как они различаются внутри кода, потому что некоторые вещи лучше всего показать визуально. Картины действительно могут захватить тысячу слов.

Поэтому мне было бы очень приятно иметь IDE, которая позволяла бы мне видеть код и изображения бок о бок, позволяя мне вставлять изображения в исходный код.

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

Еще одна вещь, о которой я мечтаю, - это визуальный отладчик, который позволяет мне программировать его так, чтобы я мог заставить некоторые из моих типов данных выводить изображение в отладчик, например, визуально видеть результаты, пока я прохожу код и проверяю алгоритмы Я пытаюсь изобрести, правильно работаю на каждом шагу и сопоставляю, как я нарисовал это на бумаге. Например, сделать так, чтобы моя сетчатая структура данных выводила визуализированное изображение в окне просмотра отладчика - идеально, если бы я мог даже сразу повернуть представление и тому подобное.

Кроме того, при работе с очень крупномасштабными кодовыми базами (десятки миллионов LOC), написанными свободными командами, имеющими около тысячи плагинов, иногда это может быть кошмаром просто для того, чтобы понять, как выполнить код, который мы ищем для некоторого неясного, редко используемый плагин из пользовательского интерфейса. В таких случаях было бы замечательно, если бы код мог встроить миниатюрный снимок экрана, показывающий, как на самом деле вызывать этот код из пользовательского интерфейса (может быть время от времени устаревшим, но обычно пользовательские интерфейсы не так нестабильны во всех случаях). версии как сделать прежние скриншоты бесполезными).

Кто-нибудь заплатит за это? Я буду.

Так или иначе, да, полностью! Я хочу чтобы!!!

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

Doxygen позволяет вставлять изображения в комментарии следующим образом:

  /*! Here is a snapshot of my new application:
   *  \image html application.jpg
   */

К сожалению, кажется, что никакие IDE не будут отображать эти изображения встроенными, но я подозреваю, что не было бы слишком сложно написать расширение VSCode, чтобы сделать это, например.

Я также нашел одно расширение VSCode, которое уже поддерживает это с другим синтаксисом commentimg . Это делается с помощью наведения мыши:

VSCode добавляет функцию, которая позволяет встроенные изображения - «кодовая вставка» - но пока еще не готова.

Вот снимок экрана с примером расширения (который я не смог найти - по-видимому, еще не выпущен, так как API для вставки кода еще не выпущен)