Guida alla digitazione del codice per non programmatori

sfondo

Ho scritto un documento scientifico contenente un codice e recentemente ho ricevuto le prove, ovvero ciò che i compositori del diario hanno creato dal mio manoscritto. Il risultato non era accettabile: il rientro è incoerente; c'è un punto fermo alla fine di ogni blocco di codice; le virgolette sono state distrutte, ecc. Si noti che tutti gli errori non erano specifici del linguaggio di programmazione che ho usato.

Ora, posso capire perché qualcuno che non ha esperienza di programmazione e risorse esterne commetterebbe tali errori, ma in tempi di Internet nessuno dovrebbe essere senza risorse esterne. Così, ho consultato il mio motore di ricerca preferito per cercare qualcosa da suggerire e ho trovato ... niente. Ci sono molte guide per i programmatori su come comporre meravigliosamente il codice in LaTeX o simili, il che è bello e appropriato, ma questo ovviamente non è fatto per il compositore che deve comporre il codice di qualcun altro.

Domanda

Sto cercando una risorsa che:

• spiega le basi del codice di composizione,
• è indirizzato ai tipografi senza esperienza di programmazione.

Forse il vero punto è che il codice non dovrebbe essere realmente composto nel modo in cui le persone comprendono la composizione. Quindi, quando si inserisce il codice in un documento, questo dovrebbe essere messo alla lettera , come in tutti gli spazi, le schede, i caratteri speciali o non speciali e le interruzioni di riga intatte.

• Le schede devono avere una larghezza di 4 o 8 spazi (quattro sono i più comuni)
• Il carattere deve essere un carattere a larghezza fissa. E deve essere quasi universalmente .

• Assicurati che la tua applicazione non effettui sostituzioni!

  Ciò significa che non ci sono legature.

  Inoltre, molti programmi (come Word e InDesign) cambiano virgolette diritte in coppie di tipografi. Assicurarsi che tali opzioni siano disabilitate prima di inserire il codice nel documento.

• Non lasciare che il codice scorra automaticamente da una riga all'altra. Non toccare il codice, non sei l'esperto!

Il codice non è un corpo del testo, non segue alcuna convenzione tipografica. Chiediti di scrivere testo in un'illustrazione?

Se sei un esperto

Se sei un esperto e conosci la lingua in questione, vale quanto segue.

Nota : non indovinare o dedurre, leggi cosa è stato detto. Molte lingue sembrano uguali e il codice potrebbe essere un pseudo linguaggio che assomiglia a codice reale. Allora puoi:

• Fai editor come colorare / grassetto / corsivo di parole chiave se e solo se la tua sostituzione ha la stessa larghezza fissa. È meglio che un editor lo faccia per te (editor come diciamo che scintilla può esportare il codice formattato). Ricorda che l'editor deve conoscere la lingua, forse anche le librerie.

  Nota che se fai questo in modo errato provoca più danni che benefici.

Se sei un esperto di dominio. Come nel conoscere la lingua e la libreria e comprendere il codice in questione:

• Quindi puoi riallineare il codice in più righe se non si adatta al tuo layout. Non farlo a meno che tu non sappia davvero cosa stai facendo, potresti finire per fare un danno irreparabile.

  La cartina di tornasole è che potresti aver scritto il codice in questione. In caso contrario, non puoi giudicare. Chiedi all'autore

  Come gestirlo? I programmatori comprendono gli standard di stile del codice. Basta scrivere nella linea guida per l'invio che è possibile inserire solo X caratteri per riga. I programmatori possono quindi farlo da soli. Gli editor di codice hanno spesso strumenti per questo. Ancora un altro motivo per usare un carattere mono spaziato.

Ma poi sapevi tutto questo, dopotutto eri un esperto. Meglio lasciare che l'autore modifichi il codice.

Numeri di riga?

Alcuni linguaggi di programmazione e casi d'uso possono trarre vantaggio dai numeri di riga. Fai attenzione qui, dato che questo è un passo falso in alcune lingue.

I problemi.

Essere consapevoli del fatto che, indipendentemente da ciò che fai, potresti effettivamente incontrare ostacoli tecnici impossibili. Il codice non dovrebbe essere realmente composto, dovrebbe essere solo testo non formattato. Questo porta a problemi sorprendenti.

Ad esempio: lingue come Python non possono essere gestite da molti visualizzatori di PDF, come Adobe Acrobat. Se si incolla il codice dal file PDF, l'editor decide di non includere lo spazio precedente quando si incolla la copia. Ciò distrugge la possibilità di incollare il codice da PDF a editor. Non c'è davvero un buon modo per gestirlo!

La risposta ovviamente può dipendere da molti fattori, ma se iniziamo con un codice di testo semplice formattato correttamente , allora si possono più o meno generalizzare le cose qui.

La "formattazione" iniziale nel testo di origine sarà: caratteri di nuova riga , spazio e tabulazione . Si noti che la nuova riga e l'interruzione manuale (come nel software DTP) non sono la stessa cosa, e viceversa, alcune lingue rare possono consentire altri caratteri di formattazione, anche se non ne ho mai sentito parlare.

I commenti non sono parte eseguibile del codice, quindi possono essere riformattati senza molti rischi, se si sa se si tratta davvero di un commento. Quindi la prima cosa da guardare è come vengono taggati i commenti.

Alcune nozioni di base sulla formattazione del testo in chiaro iniziale sono utili. Ad esempio, per Python, c'è la guida di stile PEP8 . Mentre è realizzato per Python, questa guida alla formattazione può essere utilizzata come riferimento per i principali linguaggi come C / C ++ e Java. Esaminare vari progetti di esempio può aiutare in caso di dubbio.

Pertanto, il primo principio sarebbe: non modificare il testo di origine. Vorrei passare attraverso una lista di controllo - assicurarsi che:

• Nessun autoreplacing dei caratteri si verifica su alcun palcoscenico.
• Non vengono apportate modifiche al testo (a meno che non si sia sicuri al 100% che debbano essere eseguite).
• Non viene visualizzato alcun ritorno a capo.
• Le rientranze sono conservate visivamente e sono coerenti (circa quattro x  larghezze per livello di rientranza).
• Il livello di rientro iniziale (zero) dovrebbe essere visibile.
• Gli stili definiti non distruggono la formattazione della sintassi (se si utilizza l'evidenziazione della sintassi).
• Avere un backup dell'origine in testo semplice, in modo da poter ricontrollare la formattazione originale o ricominciare da capo.
• I numeri di riga, se presenti, dovrebbero essere intatti soprattutto se sono indicati nelle spiegazioni.

In realtà, se l'origine originale è formattata correttamente, non ci dovrebbe essere alcun avvolgimento di riga. Se le linee avvolte appaiono ancora e sono inevitabili, la soluzione più comune è un rientro sospeso a un livello (vedi PEP collegato sopra). Se è necessaria l'interruzione di riga, consultare meglio la guida di stile o l'autore.

Alcuni caratteri minori di "spazio bianco" potrebbero richiedere la sostituzione. Poiché l'origine può includere caratteri di tabulazione, ciò significa ovviamente che il compositore deve garantire che tutte le schede all'inizio di ciascuna riga siano coerenti, ovvero che le rientranze nidificate siano conservate visivamente e ogni livello successivo di rientranza abbia la stessa larghezza (circa quattro x  larghezze per un livello di rientro).

Idealmente, le rientranze create con caratteri di spazio o spazi e tabulazioni misti dovrebbero essere sostituite con tabulazione (o con ciò che il software DTP può fare meglio per le rientranze nidificate), quindi, se necessario, la regolazione delle rientranze potrebbe essere più semplice.
Naturalmente si possono lasciare spazi, ma può essere più difficile gestire la loro larghezza quando si cambia il carattere e più difficile allineare le rientranze della linea interna come nelle colonne della tabella.

Carattere monospaziato + spazi

Si noti che se la sorgente è formattata intenzionalmente con spazi ed era pensata per essere letta solo in caratteri monospaziati, (ad esempio diagrammi ASCII o arte ASCII) si dovrebbero preservare gli spazi totalmente invariati , ma questa decisione dovrebbe essere presa dall'inizio. Il carattere "Courier New" è più comune per questo caso. Tuttavia, se non proprio necessario, sconsiglio il monospazio, perché oggi sempre meno persone scelgono il monospazio per la codifica e, in caso di correzione di bozze, i caratteri proporzionali daranno una migliore esperienza di lettura.

In generale, i caratteri condensati (ad es. Arial stretto) o più piccoli possono funzionare meglio: dà maggiore enfasi al contrasto con il corpo del testo, renderà il codice più compatto e quindi meno probabile che appaia un involucro di linea indesiderato.

Penso che qui si possa tracciare una linea, e se si fa quanto sopra, allora c'è una probabilità del 99% che tutto dovrebbe andare bene, almeno per un semplice blocco di codice a carattere singolo senza colori.

Strumenti e formattazione avanzata

Inoltre, l'aspetto può essere notevolmente migliorato utilizzando l'evidenziazione della sintassi.

• stampa a colori o visualizzazione dello schermo: in un layout a colori è possibile utilizzare tutte le funzionalità di evidenziazione, quindi è lo scenario migliore, ma la stampa può dare alcune variazioni di colore.

• stampa in scala di grigi o in b / n: qui ovviamente si possono usare grassetto (es. parole chiave) o corsivo (es. commenti) ma si noti che i colori saranno convertiti in grigio con tutte le conseguenze. Ad esempio, i commenti in grigio possono apparire fantastici su un display, ma possono diventare troppo chiari sulla carta.

La domanda più importante è se il produttore di layout ha strumenti che possono rappresentare il codice in una forma leggibile. Fortunatamente, ci sono molti strumenti gratuiti per la modifica del codice, i più importanti (per Windows) sono: Notepad ++, VSCode, Visual Studio . Tuttavia, tieni presente le possibili auto-conversioni implicite delle schede in spazi.

In Notepad ++ c'è un'opzione per esportare il codice come RTF , che manterrà tutta la formattazione e l'evidenziazione della sintassi della fonte.

Se il layout non richiede la modifica del flusso di testo nella presentazione del codice, è possibile utilizzare direttamente le immagini (schermate): non è così flessibile come il testo, ma conserva la formattazione e la numerazione delle linee al 100% e può risparmiare molto tempo. Ad esempio, i numeri di riga possono essere difficili da conservare in forma di testo. Anche l'esportazione in PDF è una buona alternativa, ma non tutti i software DTP possono incorporare PDF e alcune formattazioni possono andare perse durante la stampa in PDF.

Ad esempio, la mia configurazione per il codice Python in Notepad ++ è simile alla seguente:

Questo è solo per illustrare che si possono usare direttamente schermate e che in realtà potrebbe essere il metodo più semplice. Esistono vari strumenti che possono aiutare con l'acquisizione dello schermo: potrebbe essere necessario 'cucire' gli schermi per immagini a risoluzione più elevata.

La combinazione di colori è ovviamente individuale, definita nel configuratore di stili dell'editor, che è già a conoscenza del linguaggio supportato, rendendo così difficile la falsa formattazione anche se non si conosce la sintassi. Qui dovrebbero funzionare le regole generali di tipografia: non troppi colori, caratteri coerenti, rientranze, interlinea confortevole.

Sono inoltre comuni strumenti / plug-in aggiuntivi per definizioni di linguaggio personalizzate, ma richiedono conoscenze di sintassi.

In HTML, c'è un tagset <code> ... </code> che dice al lettore / interprete di trattare il contenuto in modo assolutamente letterale. inoltre, <pre> ... </pre> fa lo stesso. Come qualcuno che spesso ha dovuto comporre formule, equazioni e codice per la pubblicazione, sostengo anche l'uso delle IMMAGINI per fare questo ... creare un .gif o .jpg o .png dell'elemento problematico.

Un altro fattore è che il codice viene tradizionalmente reso in Courier monospace, o in un altro carattere monospace, perché semafora o telegrafa al lettore che non è un testo corporeo. Mi iscrivo a questa scelta di stile, penso che abbia molto senso.

Nella maggior parte dei sistemi di composizione "legacy", le equazioni matematiche di complessità ragionevolmente elevata richiedevano un tempo tremendamente lungo ... e irto di errori.