Annota il codice sorgente con diagrammi come commenti

11

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

Ho determinato solo ora che "oh, non sarebbe solo 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 di rigirare i miei algoritmi.

Come studente visualizzatore, ritengo che questo abbia il potenziale per migliorare la mia produttività con quasi ogni tipo di programmazione perché i diagrammi semplici possono aiutare a comprendere e ragionare su qualsiasi tipo di struttura 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 grafiche che potevo effettivamente disegnare rappresentazioni diagrammatiche di.

...

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

Pensavo che io o qualcun altro potessimo trovare uno strumento ragionevolmente facile da usare in grado di convertire un'immagine in una stringa binaria base64 che posso quindi inserire nel mio codice.

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

La mia ipotesi è che ci vorrebbe un po 'di tempo in più per capire 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 parsing e rendering delle immagini e mostrarle fianco a fianco con il codice, all'interno di un browser o qualcosa del genere. Dal momento che io sono un programmatore javascript di mestiere.

Che cosa pensano le persone? Qualcuno lo pagherebbe? Vorrei. Ma vorrei anche sottolineare che indipendentemente dal fatto che io o un certo numero di miei colleghi pagheremo per una cosa del genere, l'unico modo in cui una cosa del genere possa avere successo sarebbe attraverso un rilascio open source.

    
posta Steven Lu 19.11.2012 - 00:31
fonte

5 risposte

5

Che dire di plug-in di inserimento dell'immagine per Visual Studio ?

Se stai utilizzando un IDE diverso e non supporta le immagini incorporate o non hai il tempo di estenderlo, allora che ne dici di mettere un link a un'immagine nei commenti, mentre l'immagine risiederà da qualche parte nel repository?

    
risposta data 19.11.2012 - 00:36
fonte
4

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

Ciò consente di scrivere descrizioni testuali di 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:

    
risposta data 19.11.2012 - 14:33
fonte
2

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

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

Per avviare la modalità artista in emacs, fai Alt-x, digita artist-mode 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 modificarla.

    
risposta data 19.11.2012 - 03:54
fonte
1

Sembra un caso d'uso per Literate Programming in cui puoi aggiungere diagrammi e qualsiasi altra cosa alla tua documentazione.

    
risposta data 19.11.2012 - 09:59
fonte
1

What do people think? Would anyone pay for this? I would.

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

Per ora tendo a fare un sacco di "arte" ASCII come questa:

// ******************************************************
// *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 usiamo traversamenti complessi di mesh e tali per i nuovi algoritmi mesh. Questo trucco generativo del grafico di ossigeno mostrato in una delle risposte è super cool - dovrei provare di più.

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

...oquesto(confrontodelmioalgoritmochiamo"suddivisione del gancio" alla suddivisione CC standard usata da Pixar):

Fornirebbe al codice un contesto così ampio per vedere solo cosa fanno queste operazioni e come differiscono all'interno del codice, perché alcune cose sono semplicemente mostrate visivamente. Le immagini possono davvero catturare migliaia di parole.

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

Soprattutto quando inventiamo nuovi algoritmi, è difficile trovare un buon modo per descriverli in modo molto accurato (da un punto di vista tecnico, non esattamente dalla prospettiva dell'utente) senza entrare nei loro passi algoritmici poiché non c'è nulla che li possa davvero confrontare direttamente . Questi tipi di immagini prima e dopo tendono a mostrare completamente ciò che puoi aspettarti dall'algoritmo.

Un'altra cosa che sogno è un debugger visuale che mi permette di programmarlo in modo che io possa far sì che alcuni dei miei tipi di dati producano un'immagine nel debugger, ad es. per vedere visivamente i risultati mentre sto passando il codice e faccio certo che gli algoritmi che sto cercando di inventare funzionano correttamente ad ogni passo e corrispondono a come l'ho disegnato su carta. Ad esempio, fai in modo che la mia struttura di dati mesh restituisca un'immagine renderizzata nella finestra di controllo del debugger: ideale se potessi persino ruotare la vista e tale destra al suo posto.

Inoltre, quando si lavora in codebases su larga scala (decine di milioni di LOC) scritti da gruppi loose con migliaia di plugin, a volte può essere un incubo solo per capire come eseguire il codice che stiamo cercando qualche plugin oscuro, usato raramente dall'interfaccia utente. Sarebbe davvero fantastico in quei casi se il codice potesse incorporare uno screenshot in miniatura che mostra come effettivamente invocare quel codice dall'interfaccia utente (potrebbe essere soggetto a scadenze occasionali, ma solitamente le interfacce utente non sono così instabili tra versioni per rendere inutili gli screenshot precedenti.

Would anyone pay for this? I would.

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

    
risposta data 04.01.2016 - 18:27
fonte