I diagrammi ASCII valgono la pena?

I diagrammi ASCII all'interno del codice sorgente valgono il tempo che impiegano per creare?I diagrammi ASCII valgono la pena?

Potrei creare un diagramma bitmap molto più veloce, ma le immagini sono molto più difficili da allineare in un file sorgente (until VS2010).

Per la cronaca, non sto parlando di decorative ASCII art.

Ecco un esempio di un diagramma che ho recentemente creato per il mio codice che probabilmente avrei potuto creare in metà del tempo in MS Paint.

  Scenario A: 

          v 
(U)____________(N)_______<--(P)     Legend: 
      ' /   |     J = ... 
      ' /   |     P = ... 
      ' /d    |     U = ... 
      '/    |     v = ... 
      '/    |     d = ... 
      '/     |     N = ... 
     (J)     | 
      |     | 
      |___________________|

fonte

2010-04-26 Jesse Stimpson

Personalmente, preferirei avere un documento separato Word (o qualsiasi altra cosa). –

+1 Neil, se disegni cose migliori allora metti in un file separato, specialmente se puoi dare un'immagine più globale delle dipendenze del modulo con diagrammi/uml ecc. Cose che sono difficili da vedere dal codice da solo. –

Ci scusiamo, ma l'apertura del documento di Word e l'inserimento in esso è troppo lenta. È buono quando l'argomento è ampio però. A volte questi piccoli disegni ASCII sono i migliori che si possono ottenere, a meno che qualcuno non implementi RichC++, RichJava, ecc. In un modo utile. – MaR

Se si utilizza uno strumento per generare la documentazione dal proprio codice, come Doxygen, dovrebbe esserci un modo per fare riferimento a un file immagine direttamente e farlo apparire nei documenti generati. Per Doxygen, il comando rilevante è \image. Questo combina i vantaggi di avere un diagramma di immagine reale con facilità di riferimento dalla fonte (non è necessario attivare un programma pesante come Word) e anche con i documenti generati automaticamente.

fonte

2010-04-26 14:36:30 rmeador

Il vostro tempo sarebbe meglio utilizzato la scrittura di codice chiaro e conciso, con i nomi delle variabili e funzione descrittiva che non richiede commenti da capire. Né i commenti né i documenti di progettazione vengono compilati. Di conseguenza, rapidamente non sono sincronizzati con il codice e diventano fuorvianti.

fonte

2010-04-26 12:24:11

Tuttavia, con la grafica e gli algoritmi geometrici, un'immagine realmente dice più di mille parole (o linee di codice). – Thomas

Alcune cose sono molto difficili da esprimere chiaramente a parole, figuriamoci in modo conciso. Ad esempio, algoritmi non banali e routine grafiche sono spesso meglio spiegate graficamente. – Kramii

Nel codice di produzione reale che è in realtà piuttosto raro. Di solito ci si aspetta che le persone che lavorano sul codice abbiano familiarità con il dominio del problema. Non è responsabilità dei commenti o dei documenti di progettazione insegnare loro il dominio del problema. Per esempio, mi aspetto che il lettore di codice che gestisce le trasformazioni grafiche 2D in una libreria di imposizione capisca come funzionano le trasformazioni grafiche 2D. Non metterei insieme un documento che lo spieghi come parte del mio codice o disegno. –

Prova questo: bella libreria per metterli insieme dinamicamente. http://code.google.com/p/clojure-textflow/

fonte

2010-04-26 12:24:33

Questo copre solo un sottoinsieme molto limitato di diagrammi che potresti voler includere nel codice sorgente. –

Esistono altri strumenti che potrebbero essere utili, ad es. http://www.jave.de/ – Kramii

@Kramii, app molto bella. Grazie per il suggerimento –

Quindi utilizzare MS Paint (o qualsiasi altra cosa) e includere il diagramma nel controllo sorgente.

fonte

2010-04-26 12:41:01 Kramii

La documentazione di progettazione appartiene a un documento di progettazione. Perché non avere una cartella di progetto con sottocartelle per disegni, manuali, sorgenti, file di esempio, test case, liste dei desideri, registri delle modifiche, ecc. Non sto dicendo che ogni tipo di documento abbia bisogno di una directory separata, ma le cose dovrebbero essere organizzate logicamente .

Il tempo di aprire il file esterno non è un problema accanto al tempo sprecato per creare l'arte ASCII e quanto rapidamente si rompe quando qualcuno usa un editor o un font diverso.

fonte

2010-04-26 12:58:00 Ron

Conosci il tuo pubblico. Il tuo pubblico (altri sviluppatori in futuro) sarà in grado di accedere alla bitmap in modo semplice e facile con gli strumenti a sua disposizione? Il diagramma è utile/utile?

Un diagramma ASCII nei commenti del codice può quasi sempre essere visualizzato facilmente. (Sì, potrebbero esserci alcuni problemi se sono stati utilizzati i caratteri ASCII estesi o se lo sviluppatore sta utilizzando un carattere non fisso.)

fonte

2010-04-26 13:47:41 Sparky

se si codifica con un font non fisso che è strano a dir poco: P –

@ Looris, dovrei essere d'accordo. Tuttavia, potrebbe comunque essere comune che il codice venga visualizzato con un carattere di larghezza non fissa. La nostra versione dello strumento di confronto di ClearCase utilizza un carattere non fisso per impostazione predefinita. Questo rende tutto brutto come il peccato. –

Concordo con la maggior parte degli altri poster: tutto ciò che non è codice (e un po ' di commenti, ma non troppo verbosi) dovrebbe essere da qualche altra parte, che si tratti di un wiki o di un documento.

Preferisco evitare Word a causa di vari contrattempi che ho sofferto in passato, ma questa potrebbe essere una preferenza personale. Un'ultima cosa: prova ad avere un buon nome per le cose e usale come collegamento tra il tuo codice e i tuoi documenti. Quindi se hai una classe (o una routine, o un modulo) che si occupa di scenari come quello che hai mostrato come esempio, per favore chiama SquareBisector o qualcosa di simile, e i suoi metodi sono scenarioA (Punto a, Punto b), scenarioB (Punto a, Riga l1) e così via, e quindi scrivere i documenti spiegandoli in termini più elevati, con abbondanza di diagrammi, in un documento usando una terminologia coerente.

Si prega di non chiamare i tuoi metodi "bisectWithTwoPoints (Point firstPoint, Point secondPoint) nel codice e 'Scenario A' nella documentazione ...

fonte

2010-04-26 14:15:10

Hai guardato nelle varie convertitori arte ASCII là fuori? In questo modo puoi disegnare rapidamente in vernice o qualsiasi altra cosa e poi esportare l'arte ASCII.

fonte

2010-04-26 14:28:35 jamone

È possibile convincere tutti nel proprio team a utilizzare VS2010 e solo embed actual images nel file di origine.

fonte

2010-04-26 14:41:25 Eclipse

Sì, ho familiarità con quella meraviglia. Purtroppo non è un'opzione per noi in questo momento, ma ci stiamo adoperando. –

A volte un diagramma ASCII vale davvero più di mille parole. Ma non molto spesso. Non andrò a cercare tutti i miei file sorgente, ma immagino che un diagramma per 20.000 righe di codice possa essere corretto (o almeno non spento di più di un fattore due).

Chiunque suggerisca di inserire il codice in un punto e il diagramma in un altro è solo supplicando affinché i due diventino incoerenti. Meglio non avere diagrammi o diagrammi ASCII scadenti di un documento Word separato sbagliato.

fonte

2010-04-26 23:56:19

È possibile utilizzare http://www.asciiflow.com per disegnare diagrammi di classe/flusso piuttosto semplici e simili. È interamente basato sul web, usando javascript. Consigliato Chrome/Firefox.

fonte

2011-06-13 18:46:49 J3SUS666

Ho compilato un elenco di collegamenti e un piccolo tutorial per disegnare diagrammi ASCII su Python Wiki. Qualsiasi foto che ti faccia risparmiare tempo leggendo il testo vale sicuramente la pena.

fonte

2013-11-21 20:37:30

risposta

Problemi correlati