Annota il codice sorgente con diagrammi come commenti

Scrivo molto codice (principalmente c ++ e javascript) che tocca la geometria computazionale e la grafica e quel tipo di argomenti, quindi ho scoperto che i diagrammi visivi sono stati una parte indispensabile del processo di risoluzione dei problemi.

Ho determinato proprio ora che "oh, non sarebbe fantastico se potessi in qualche modo allegare un diagramma disegnato a mano a un pezzo di codice come commento", e questo mi permetterebbe di tornare a qualcosa su cui ho lavorato, giorni, settimane, mesi prima e molto più rapidamente ri-grok i miei algoritmi.

Come studente visivo, credo che questo abbia il potenziale per migliorare la mia produttività con quasi tutti i tipi di programmazione perché semplici diagrammi possono aiutare a comprendere e ragionare su qualsiasi tipo di struttura di dati non banale. Grafici per esempio. Durante la lezione di teoria dei grafi all'università ero sempre stato in grado di comprendere veramente le relazioni tra grafi di cui potevo effettivamente disegnare rappresentazioni schematiche.

Così...

Nessun IDE a mia conoscenza ti consente di salvare un'immagine come commento al codice.

Pensavo che io o qualcun altro potremmo escogitare uno strumento ragionevolmente facile da usare che può convertire un'immagine in una stringa binaria base64 che posso quindi inserire nel mio codice.

Se il processo di conversione / inserimento può essere abbastanza semplificato, consentirebbe una connessione molto migliore tra il diagramma e il codice reale, quindi non ho più bisogno di cercare cronograficamente i miei notebook. Ancora più fantastico: plugin per gli IDE per analizzare automaticamente e visualizzare l'immagine. Non c'è assolutamente nulla di difficile da questo punto di vista teorico.

La mia ipotesi è che ci vorrebbe un po 'di tempo extra per capire davvero come estendere i miei IDE preferiti e mantenere questi plugin, quindi sarei totalmente felice con una sorta di post-processore di codice che farebbe lo stesso analizzando e rendering delle immagini e mostrale fianco a fianco con il codice, all'interno di un browser o qualcosa del genere. Dal momento che sono un programmatore javascript per commercio.

Cosa pensano le persone? Qualcuno pagherebbe per questo? Vorrei. Ma forse vorrei anche sottolineare che indipendentemente dal fatto che io o un numero significativo dei miei colleghi pagheremmo per una cosa del genere, l'unico modo in cui una cosa del genere avrà successo sarebbe attraverso una versione open source.

Che dire del plug-in Image Insertion per Visual Studio ?

Se stai usando un IDE diverso e non supporta immagini incorporate o non hai tempo per estenderlo, allora che ne dici di inserire un link a un'immagine nei commenti, mentre l'immagine risiederebbe da qualche parte nel repository ?

Se non sei un artista ASCII , puoi usare doxygen come strumento di documentazione insieme a dot / graphviz integrato ad esso.

Ciò consente di scrivere una descrizione testuale dei grafici e renderli nella documentazione.

Ad esempio, questa descrizione:

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)" ];
}

viene visualizzato come:

Potresti provare la modalità artista di emacs. Farebbe arte ascii piuttosto che immagini di per sé, quindi potrebbe o meno essere quello che stai cercando. In particolare, se il tuo IDE non esegue caratteri a larghezza fissa, non sarebbe utile. Essendo testo semplice, giocherebbe molto bene con il controllo della versione.

Ecco uno screencast della modalità artista in uso, quindi puoi avere un'idea se sei interessato o no.

Per avviare la modalità artista in emacs, fai Alt-x, digita modalità artista e premi invio. Il pulsante centrale del mouse fa apparire il menu. Le combinazioni di tasti per taglia e incolla non sono quelle normali di Windows per impostazione predefinita, ma è possibile attivare la modalità CUA per modificarlo.

Cosa pensano le persone? Qualcuno pagherebbe per questo? Vorrei.

ZOMG, mi inserisco in una categoria simile a te e mi piacerebbe una tale funzione direttamente nell'IDE.

Per ora tendo a fare un sacco di "arte" ASCII in questo modo:

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

Il valore principale che trovo è vedere i nomi delle variabili corrispondenti al diagramma visivo, specialmente quando stiamo usando traversate complesse di mesh e simili per nuovi algoritmi di mesh. Questo trucco generatore di grafici di Doxygen mostrato in una delle risposte è fantastico - Dovrei provare di più.

Ci sono così tante cose che sono più facili da comunicare anche visivamente, non necessariamente nemmeno usando i grafici. Esempio:

... o questo (confronto del mio algoritmo che sto chiamando "suddivisione hook" con suddivisione CC standard utilizzata da Pixar):

Darebbe al codice un tale contesto per vedere semplicemente cosa fanno queste operazioni e come differiscono all'interno del codice perché alcune cose sono solo meglio visualizzate visivamente. Le immagini possono davvero catturare più di mille parole.

Quindi sarebbe totalmente sognante per me avere un IDE che mi permettesse di vedere il codice e le immagini fianco a fianco, permettendomi di incorporare le immagini nel codice sorgente.

Soprattutto quando stiamo inventando nuovi algoritmi, è difficile trovare un buon modo per descriverli in modo molto accurato (da una prospettiva tecnica, non esattamente la prospettiva dell'utente) senza andare nei loro passi algoritmici poiché non c'è nulla con cui confrontarli direttamente. Questi tipi di immagini prima e dopo tendono a mostrare immediatamente cosa ci si può aspettare dall'algoritmo.

Un'altra cosa che sogno è un debugger visivo che mi permetta di programmarlo in modo da poter fare in modo che alcuni dei miei tipi di dati producano un'immagine nel debugger, ad es. Per vedere visivamente i risultati mentre passo attraverso il codice e mi assicuro che gli algoritmi Sto cercando di inventare che stanno funzionando correttamente ad ogni passo e abbinando il modo in cui l'ho disegnato su carta. Ad esempio, fai in modo che la mia struttura di dati mesh metta in output un'immagine renderizzata nella finestra di controllo del debugger, ideale se potessi anche ruotare la vista e simili in quel momento.

Inoltre, quando si lavora in basi di codice su larga scala (decine di milioni di LOC) scritti da squadre sciolte con come un migliaio di plugin, a volte può essere un incubo solo per capire come eseguire il codice che stiamo cercando per qualche oscuro, plugin usato raramente dall'interfaccia utente. Sarebbe fantastico in quei casi se il codice potesse incorporare uno screenshot in miniatura che mostra come invocare effettivamente quel codice dall'interfaccia utente (potrebbe essere incline a scadere di tanto in tanto di tanto in tanto, ma di solito le UI non sono così instabili in tutti versioni per rendere inutili gli screenshot precedenti).

Qualcuno pagherebbe per questo? Vorrei.

Quindi comunque, sì, totalmente! Lo voglio!!!

Sembra un caso d'uso per la programmazione letterata in cui è possibile aggiungere diagrammi e quant'altro alla documentazione.

Doxygen ti consente di inserire immagini in commenti come questo:

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

Sfortunatamente sembra che nessun IDE mostrerà queste immagini in linea, ma sospetto che non sarebbe troppo difficile scrivere un'estensione VSCode per farlo ad esempio.

Ho anche trovato un'estensione VSCode che già supporta questo con un commento diverso di sintassi . Lo fa tramite un passaggio del mouse:

VSCode sta aggiungendo una funzione che consente immagini incorporate - "inserto di codice" - ma non sembra essere ancora pronto.

Ecco uno screenshot dall'estensione di esempio (che in realtà non riuscivo a trovare - presumibilmente non è stato ancora rilasciato poiché l'API di inserimento del codice non è ancora stata rilasciata)