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

14

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

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

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

Так...

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

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

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

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

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

Стивен Лу
источник
4
Альтернатива: комментарий в ссылке на локальный файл изображения, который открывается в программе просмотра изображений по умолчанию.
Hand-E-Food
Мой самый большой страх - злоупотребление системой. Конечно, это начинается с диаграммы, имеющей смысл для сложного алгоритма, но как долго, пока кто-нибудь не загрузит надуманные документы спецификации в комментарии для класса? Прежде чем вы это знаете, все, что связано с проектом и разработчиком, помещается в комментарии к коду. Конечно, любая мощная система открыта для злоупотреблений. Я думаю, что это ниша, но если вы находитесь в этой нише, это был бы очень полезный инструмент.
Snixtor
@ Hand-E-Food Ницца! URL-адрес файла в комментарии отображается в виде интерактивной ссылки в Xcode из коробки. Моя единственная жалоба на это заключается в том, что создание URL-адреса файла относительного пути кажется невозможным, поэтому при переключении систем аспект интерактивной ссылки прерывается (по всей вероятности).
Стивен Лу
Возможно, вас заинтересуют неориентированные графы или деревья
TehShrike
Я делаю Javadoc, который будет генерировать HMTL, с изображениями. Или SimpleDocBook, отдельная документация, основанная на XML, на которую можно / нужно ссылаться в коде бизнес-правил. Это дает хорошую прозу и охватывает систему вне перспективы всей бизнес-логики, а не распределенных программных компонентов и уровней (классов). Каждый запрос на изменение добавляет код со ссылкой в ​​качестве docbook + номер версии / тикета, и в docbook есть список изменений + номер тикета. Это работает из-за его полного охвата. Не уверен, как это будет соответствовать вашей ситуации.
Joop Eggen

Ответы:

6

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

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

Арсений Мурзенко
источник
Это круто. Я использую VS на работе, так что я могу попробовать это! Благодарю. Сохранение изображения в репозитории и его связывание - это, безусловно, один из способов сделать это, но я уверен, что для меня это все еще слишком сложно для надежной реализации. Я довольно ленивый программист.
Стивен Лу
Сохранение картинок в репо также будет работать с большинством методов просмотра репо (например, веб-интерфейс репозитория VCS)
Стивен Лу,
4

Если вы не являетесь художником 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)" ];
}

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

введите описание изображения здесь

mouviciel
источник
Это круто! Любая инструментальная поддержка для сред Java? Я не вижу ничего похожего на поддержку этого в этом Mojo, например: graphviz-maven-plugin.bryon.us/dot-mojo.html . Все остальные также только что поддержали файлы .dot.
oligofren
2

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

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

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

Майкл Шоу
источник
Вау, это ... впечатляет. У меня на самом деле есть несколько комментариев в стиле диаграммы ASCII в моем коде. Это просто слишком много времени. Я хочу использовать лучшие инструменты, потому что технология уже здесь. Иногда я писал код на Vim, но какие скрипты с распознаванием кода мне не удавались по сравнению с реальными IDE. Но спасибо, что показали мне эту технику старой школы!
Стивен Лу
Посещение несколько лет спустя, и с тех пор я собрал несколько вкусностей Vim, чтобы помочь в быстрой сборке коробочных диаграмм. будь то символы ASCII или Unicode, это очень крутой способ украсить некоторый код классными и полезными комментариями. Однако Vim не поставляется ни с чем из коробки.
Стивен Лу
1

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

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), написанными свободными командами, имеющими около тысячи плагинов, иногда это может быть кошмаром просто для того, чтобы понять, как выполнить код, который мы ищем для некоторого неясного, редко используемый плагин из пользовательского интерфейса. В таких случаях было бы замечательно, если бы код мог встроить миниатюрный снимок экрана, показывающий, как на самом деле вызывать этот код из пользовательского интерфейса (может быть время от времени устаревшим, но обычно пользовательские интерфейсы не так нестабильны во всех случаях). версии как сделать прежние скриншоты бесполезными).

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

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


источник
1
Потрясающие картинки и спасибо за рецензию (хотя это скорее комментарий, чем ответ)! Недавно я решил полностью отдохнуть от классной графики и симуляторов и создать инструменты отладки и трассировки следующего поколения . То, о чем ты мечтаешь, очень похоже на то, о чем я мечтаю ...
Стивен Лу
1
@StevenLu Я часто мечтал создать такую ​​IDE, которую вы предлагаете, с помощью визуального отладчика (хотя я думал о том, чтобы сделать это с нуля, так как я не мог представить себе решение для плагинов, которое так хорошо работает на стороне отладчика). Но да - я думаю, что ответ был своего рода комментарием ... но я был просто счастлив увидеть кого-то другого, желающего этого. Мои коллеги в прошлом были более техничными и математическими типами - они не совсем понимали мое желание все визуально донести.
1
Возможно , один псевдо-научный способ смотреть на это является то , что зрительная система является , несомненно , самой высокой пропускной способностью интерфейса мы , как люди, и хотя это отстой , что у нас есть только он доступен для использования в качестве входных данных, глубокая интеграция зрительной системы в Доступ к мозговой памяти позволяет визуальным форматам получить безусловное преимущество для документирования и распространения абстрактных концепций. ... С этой целью я работаю над независимым от IDE инструментом (следуя философии Unix), который позволяет скомпилированным приложениям автоматически генерировать структурированные визуальные представления его внутренних компонентов, чтобы мы могли их понять.
Стивен Лу
0

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

Восстановить Монику - М. Шредер
источник
Почему отрицательный голос?
Восстановить Монику - М. Шредер,
Я проголосовал за тебя. Это очень хорошее наблюдение, то, что я обсуждаю, почти полностью подпадает под этот зонтик.
Стивен Лу
1
Я тоже проголосовал, потому что это не дает ответа. Он явно не хочет переключать всю свою программу на грамотный стиль программирования, и даже если он это сделал, грамотное программирование - это всего лишь подход к программированию - это не обязательно означает, что диаграммы и изображения поддерживаются.
Тимммм
0

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

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

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

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

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

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

Timmmm
источник