Sono attualmente in un corso di statistica presso Uni. Dobbiamo presentare relazioni sui risultati insieme al codice che abbiamo usato. Mi chiedo quale sia il modo migliore per presentare questo codice nei report. Una pagina separata con un riferimento al report o in linea. O qualcos'altro?
Grazie
Se ti riferisci solo a piccole parti del codice, posizionalo sulla stessa pagina dove stai parlando. Nessuno può leggere più del valore del codice della pagina se può aiutarla.
Per una separazione immediata tra codice dal testo inglese, utilizzare:
Un lato irrilevante: per i segni di bonus subconsci, usa qualcosa come il lattice. Poiché le persone che contrassegnano il tuo rapporto (molto probabilmente) lo apprezzerebbero.
Oltre a @Jonathan , alcuni punti da quando ho dovuto presentare il codice in un rapporto:
Fai qualcosa del genere e ....
Attaccalo su link o link o qualcosa e includi l'URL!
Se esiste la possibilità che vogliano effettivamente eseguire il codice per vedere quanto è bello il tuo report, questo renderà molto facile farlo. Potrebbero apprezzare il pensiero anche se non lo eseguono effettivamente.
Quanto codice? Alcune righe, probabilmente fino a un terzo di una pagina, funzionano in linea. Più di questo e probabilmente stai meglio inserendolo in un'appendice.
Vorrei usare entrambi: menziona la parte più rilevante del codice inline (in piccole parti, tutti i dettagli irrilevanti lasciati fuori, forse solo firme o parti di metodo), quindi fornisci il codice completo o almeno il codice e il contesto rilevanti come appendice . (Altri modi di presentare il codice completo potrebbero essere un'opzione, online o un cd o qualcosa del genere. Dipende dal rapporto e dal pubblico di destinazione.) Il codice inline dovrebbe essere abbastanza breve da essere solo un'illustrazione del punto che fai nel tuo testo. Il codice completo nell'appendice dovrebbe essere sufficientemente esteso in modo che chiunque possa controllare le tue conclusioni.
Rendi gli esempi di codice visivamente distinti e sottotitoli e / o numerali, come faresti con blocchi di testo, illustrazioni, grafici, tabelle, ecc. Vorrei anche menzionare dove nell'appendice è possibile trovare il frammento di codice inline.
Oltre alle altre risposte, ti consiglio di utilizzare un carattere a larghezza variabile per il testo discorsivo e una larghezza fissa per il codice. Non solo questo imita il modo in cui il codice e la copia sono interconnessi nella maggior parte dei libri e online (ciao Stack Overflow !), Ma implica anche chi è il pubblico previsto del testo.
Il carattere a larghezza variabile sembra essere pensato per le persone. Il carattere a larghezza fissa sembra robotico e come se fosse pensato per le macchine: in realtà viene richiamato quando il testo è stato disposto in righe e colonne rigorose su uno schermo e viene prestata poca attenzione alla leggibilità.
Dipende da quanto è legato il codice al report. Se il tuo rapporto riguarda principalmente i tuoi risultati, allora aggiungerei semplicemente il codice sorgente come appendice alla fine del documento.
Se il tuo rapporto include dettagli sul codice o sugli algoritmi che stai utilizzando, includi comunque una copia completa nell'appendice, ma includi frammenti di codice pertinente in linea con il documento.
Se utilizzi LaTeX, ti suggerisco di utilizzare il pacchetto Listings per il codice sorgente. Questo crea una bella cornice attorno al codice con un'intestazione ombreggiata, con un font monospace e l'evidenziazione della sintassi per la maggior parte delle lingue, e puoi etichettare i frammenti in modo che tu possa \ ref {listing: foo} nel tuo documento.
Leggi altre domande sui tag documentation reporting