Анотувати вихідний код із діаграмами як коментарі

Я пишу багато (в першу чергу c ++ та javascript) коду, який стосується обчислювальної геометрії та графіки та подібних тем, тому я виявив, що візуальні діаграми були невід'ємною частиною процесу вирішення задач.

Я зараз вирішив, що "о, чи не було б просто фантастично, якби я міг якось прикріпити мальовану діаграму до фрагмента коду як коментар", і це дозволило б мені повернутися до чогось, над чим я працював, дні, тижні, місяці раніше і набагато швидше переробляють мої алгоритми.

Як візуальний студент, я відчуваю, що це має потенціал покращити свою продуктивність майже при кожному типі програмування, оскільки прості діаграми можуть допомогти зрозуміти та міркувати про будь-який тип нетривіальної структури даних. Наприклад, графіки. Під час уроку теорії графів в університеті я лише коли-небудь міг по-справжньому зрозуміти взаємозв'язки графів, про які я міг насправді скласти схематичні уявлення.

Так...

Наскільки мені відомо, IDE не дозволяє зберегти зображення як коментар до коду.

Моя думка полягала в тому, що я або хтось інший міг придумати якийсь досить простий у використанні інструмент, який може перетворити зображення в двійкову рядок base64, яку потім я можу вставити у свій код.

Якщо процес перетворення / вставки може бути досить впорядкованим, це дозволить набагато кращим зв’язком між діаграмою та фактичним кодом, тому мені більше не потрібно хронографічно шукати свої ноутбуки. Ще дивовижніше: плагіни для IDE автоматично розбирають і показують зображення. З цього питання абсолютно нічого складного з теоретичної точки зору.

Я здогадуюсь, що мені знадобиться додатковий час, щоб я дійсно з'ясував, як розширити свої улюблені IDE та підтримувати ці плагіни, тому я був би абсолютно задоволений таким кодом постпроцесором, який би зробив такий самий аналіз і візуалізація зображень і показує їх поряд з кодом, всередині браузера чи чогось іншого. Оскільки я програміст javascript в галузі торгівлі.

Що думають люди? Хтось заплатив би за це? Я би. Але, можливо, я також зазначив, що незалежно від того, чи я чи якась значна кількість моїх однолітків заплатили б за таку річ, єдиний спосіб, який, можливо, досягне успіху, - через випуск з відкритим кодом.

Що щодо плагіна вставки зображень для 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. Це робило б мистецтво ascii, а не зображення як таке, тому воно може бути чи не бути тим, що ви шукаєте. Зокрема, якщо ваш IDE не робить шрифти фіксованої ширини, це не буде корисним. Будучи простим текстом, він буде грати дуже добре з контролем версій.

Ось скріншот використовуваного режиму виконавця, тож ви можете зрозуміти, хочете ви цього чи ні.

Щоб запустити режим виконавця в emacs, виконайте Alt-x, введіть режим виконавця та натисніть клавішу 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*
// ******************************************************

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

Є так багато речей, що простіше спілкуватися і візуально, не обов'язково навіть за допомогою графіків. Приклад:

... або це (порівняння мого алгоритму я називаю "підключення підключення" до стандартного підрозділу CC, як використовується Pixar):

Це дало б коду стільки контексту, щоб просто побачити, що роблять ці операції та як вони відрізняються всередині коду, оскільки деякі речі просто найкраще відображаються візуально. Фотографії дійсно можуть охопити тисячу слів.

Тож мені було б абсолютно мріяти мати IDE, який дозволив би мені бачити код і зображення поруч, що дозволяло мені вставляти зображення у вихідний код.

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

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

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

Хтось заплатив би за це? Я би.

Так що все одно, так, повністю! Я хочу, щоб!!!

Здається, що ви хочете використовувати для грамотного програмування, де ви можете додавати діаграми та все, що завгодно до вашої документації.

Doxygen дозволяє вставляти зображення в такі коментарі:

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

На жаль, схоже, що жоден IDE не відображатиме ці зображення вбудовано, але я підозрюю, що було б не надто важко написати розширення VSCode, щоб це зробити, наприклад.

Я також знайшов одне розширення VSCode, яке вже підтримує це з іншим синтаксисним коментарем . Це робиться за допомогою наведення курсору:

VSCode додають функцію, яка дозволяє вбудовані зображення - "вставка коду" - але, здається, вона ще не готова.

Ось скріншот із зразка розширення (якого я фактично не міг знайти - імовірно, його ще не було випущено, оскільки API введення коду ще не випущений)