Numerare le righe di un testo per una revisione a più mani

Perché un testo condiviso ha bisogno di numeri

Il codice arriva già con i numeri. L'editor li stampa nel margine sinistro, un diff li stampa da entrambi i lati della modifica e un commento di revisione su una piattaforma di hosting si aggancia a uno di essi. La prosa no. Una clausola di contratto, una serie di sottotitoli, un export di memoria di traduzione, un elenco di nomi di prodotto da controllare in due: nessuno di questi testi ha un modo stabile di dire «il quarto dall'alto» che non sia contare.

È il conteggio a mano che manda in malora la revisione. Due persone contano da punti diversi, una include la riga vuota e l'altra no, e un'ora dopo ci sono due correzioni sulla stessa clausola e una su una clausola che nessuno voleva toccare. Attaccare un numero a ogni riga prima di far circolare il testo elimina tutta questa famiglia di equivoci al prezzo di un incolla.

La parola importante è «prima». I numeri sono un sistema di coordinate, e un sistema di coordinate serve solo finché sta fermo. Se qualcuno rinumera un testo già annotato, ogni commento diventa un indovinello. Numera una volta, fai circolare esattamente quella versione e raccogli le correzioni rispetto a essa.

Che cosa produce davvero lo strumento

L'impostazione predefinita è un punto seguito da uno spazio: «first line» diventa «1. first line». Sono offerti altri dieci separatori: «1) », «1: », «1 - », «1 | », «[1] », «1] », «#1 », «1 → », uno spazio semplice e una tabulazione. Due di essi racchiudono il numero invece di seguirlo, ed è per questo che «[1] » e «#1 » hanno un aspetto diverso.

L'allineamento si calcola dall'ultimo numero e si applica con spazi normali, non con zeri. Un testo di 102 righe torna con « 1. line1» in cima e « 102. line102» in fondo, con le cifre allineate a destra. La larghezza si decide una volta sola, prima della prima riga, quindi un testo di 99 righe ha larghezza due e uno di 100 righe larghezza tre: uno spazio in più su ogni riga per una sola riga aggiunta. Se stai confrontando due versioni numerate, ecco perché tutte le righe risultano modificate.

Vale la pena conoscere tre piccoli comportamenti prima di incollare qualcosa di lungo. Un a capo finale produce una riga vuota numerata in fondo, perché dividere «a\nb\n» sugli a capo dà tre pezzi e il terzo è vuoto: l'output finisce con «3. ». Un input vuoto produce «1. » anziché nulla. E un input con fine riga Windows torna con fine riga Unix: la divisione accetta un ritorno a capo prima dell'avanzamento di riga, ma la ricomposizione rimette solo l'avanzamento di riga.

Iniziare da 1, e solo da 1 — o da un numero negativo

Il campo «Inizia da» esiste perché un estratto numerato di solito viene da qualche parte: la pagina quattro di una trascrizione non dovrebbe ripartire da 1. Mettilo a 500 e l'output dà 500, 501, 502, con larghezza tre. Fin qui funziona come promesso.

Lo zero è l'eccezione, e non è un difetto che si aggiri scrivendolo in altro modo. Il valore è letto come Number(start) || 1. Lo zero è uno dei valori falsy di JavaScript, quindi l'espressione ricade su 1: digitare 0 e non digitare nulla danno lo stesso risultato. Chi voleva una numerazione in stile array, con la prima riga come riga 0, qui non l'avrà. Un campo vuoto si comporta allo stesso modo, e anche un valore che non è un numero: «abc» dà 1.

Gli avvii negativi, curiosamente, funzionano, perché −3 è truthy. Tre righe che partono da −3 tornano come «-3. », «-2. », «-1. »: non serve a nulla di preciso, ma dice che la protezione riguarda la falsiness e non il segno. I valori frazionari sono arrotondati verso meno infinito: 2,7 diventa 2 e −2,7 diventa −3.

Il ritorno, che non è simmetrico

remove-line-numbers non ha alcuna opzione. Applica un unico schema a ogni riga: spazi o tabulazioni iniziali, poi il numero e il suo marcatore — cifre seguite da una tabulazione, o cifre fra parentesi quadre o precedute da un cancelletto, o cifre seguite da un punto, una parentesi chiusa, due punti, una parentesi quadra chiusa o una freccia — e infine un solo spazio, oppure la fine della riga. Tutto ciò che combacia viene cancellato, una volta per riga. Due dettagli di quella frase fanno tutto il lavoro: il marcatore deve essere seguito da uno spazio, e lo spazio consumato è esattamente uno.

Passa tutti e undici i separatori nello strumento e otto sopravvivono al viaggio: punto, parentesi, due punti, tabulazione, «[1] », «1] », «#1 » e «1 → » tornano esattamente al testo di partenza. Tre no, e l'omissione è voluta. «1 - alpha», «1 | alpha» e «1 alpha» tornano immutati, numeri ancora attaccati, perché «5 - 3 = 2», «10 - 20 people», «1 | Alice | 30» e «007 James» hanno esattamente la stessa forma e sono contenuto molto più spesso che numerazione. Uno strumento di rimozione che annullasse quei tre si mangerebbe una riga di foglio di calcolo ogni volta che qualcuno ne incolla una.

Lo schema finiva con una sequenza golosa di spazi, che si portava via l'indentazione del testo; ora ne prende esattamente uno. Numera cinque righe di JavaScript con una funzione, un if e un return, togli i numeri, e il file torna byte per byte, indentazioni comprese. YAML e Python si comportano allo stesso modo, ed è lì che conta di più: in quei due linguaggi un risultato appiattito non è solo brutto, non vuole più dire la stessa cosa.

Chi rimuove non può sapere di chi sia il numero

Questo è il limite onesto dell'intera idea, e la regola dello spazio lo restringe senza toglierlo. «1. Lavare il riso» è una riga numerata se l'1 ce l'ha messo lo strumento, ed è contenuto se ce l'ha messo il cuoco. Nulla nella stringa distingue le due cose, e nessuno schema può farlo: quelle due righe sono gli stessi byte. Pretendere uno spazio dopo il separatore esclude gli incidenti — «3.14 is pi» e «1.2.3 version» tornano ora intatti, perché un punto decimale non è mai seguito da uno spazio — ma non esclude le coincidenze. «12: 30 departure» torna ancora come «30 departure». «2026. A year.» torna ancora come «A year.» Entrambe sono, carattere per carattere, ciò che add-line-numbers scrive; su una riga che nessuno ha numerato, resta perdita di dati.

Due cose tengono al sicuro il caso ordinario. La cancellazione avviene una volta per riga e si ferma al primo separatore: un listino scritto all'inglese, numerato, dà «1. 12.50 Coffee», e togliere il numero riconosce «1. » e si ferma, restituendo «12.50 Coffee» intatto; un elenco che aveva già i suoi numeri, «1. 1. alpha», perde esattamente un livello. E quella riga di prezzo ora sopravvive anche senza la numerazione, perché il punto di «12.50» non è seguito da uno spazio. Il viaggio di andata e ritorno è quindi sicuro su qualunque testo, indentato o piatto, con uno qualsiasi degli otto separatori. A mordere resta solo lo strumento di rimozione da sé, applicato a un testo che nessuno ha numerato, sul ristretto insieme di righe che somigliano al suo stesso output.

Capire perché qualcosa è sicuro è più utile dell'elenco. Un CSV di identificativi sopravvive — «1024, Dupont, 42» torna intatto — perché il carattere dopo le cifre è una virgola, e la virgola non compare in nessuna delle forme di marcatore. «100 units of flour» e «007 James» sopravvivono perché nemmeno uno spazio semplice lo è. I decimali e le versioni semantiche sono sicuri anch'essi, ma per l'altra ragione: «3.14» e «1.2.3» un punto ce l'hanno, e a salvarli è che non lo segue alcuno spazio. A rischio è il ristretto insieme in cui un numero, un marcatore riconosciuto e uno spazio arrivano in quest'ordine: gli anni usati come titoli, «12: 30» scritto con lo spazio dopo i due punti, e — novità da quando l'insieme dei marcatori si è allargato — i richiami di nota del tipo «[1] » e le righe che aprono con «#1 ».

Condurre la revisione senza perdere nulla

Tieni l'originale non numerato dove non lo sovrascriverai e tratta la versione numerata come una stampa: qualcosa da leggere, citare e annotare, non da modificare e rispedire. Ogni correzione raccolta come «riga 47, sostituire X con Y» si applica pulitamente all'originale, e i numeri non vanno mai tolti.

Se hai davvero intenzione di togliere i numeri più tardi, evita esattamente tre separatori: il trattino, la barra verticale e lo spazio semplice. Tutto il resto del menù — punto, parentesi, due punti, tabulazione, «[1] », «1] », «#1 », «1 → » — si toglie senza problemi. Preferisci la tabulazione se il testo passerà vicino a un foglio di calcolo: mette i numeri in una colonna propria.

Numerare codice che intendi reincollare ora è sostenibile, cosa che prima non era: con un punto, una parentesi, due punti o una tabulazione il file torna byte per byte, indentazione compresa. Resta comunque di rado la mossa giusta — una revisione di codice ha strumenti migliori: un diff, una pull request, o semplicemente i numeri di riga che l'editor sta già mostrando a entrambi — ma se lo fai, scegli uno di quei quattro e prova prima l'andata e ritorno su una copia.

Domande frequenti

Posso far partire la numerazione da 0?

No, e non c'è trucco che lo aggiri. Lo strumento legge il campo come Number(start) || 1. Lo zero è falsy in JavaScript, quindi l'espressione lo scarta e restituisce 1: digitare 0, lasciare il campo vuoto o digitare una parola producono tutti un elenco che parte da 1. Verificato con 0, «0», «» e «abc»: tutti e quattro hanno dato lo stesso output. Se ti serve una numerazione da zero, numera da 1 e sottrai uno a mente, oppure numera da −1 se conta più lo scarto del segno: gli avvii negativi funzionano, perché un numero negativo è truthy.

I numeri restano allineati una volta superate le 100 righe?

Sì. La larghezza è calcolata dall'ultimo numero prima di scrivere qualsiasi cosa, e ogni numero è riempito a sinistra con spazi fino a quella larghezza. Un testo di 102 righe comincia con due spazi davanti alla riga 1 e nessuno davanti alla 102: i punti formano una colonna dritta. Non ci sono zeri iniziali: ottieni « 7. », mai «007. ». Una conseguenza coglie molti di sorpresa: un testo di 99 righe usa larghezza due e lo stesso testo con una riga in più usa larghezza tre, quindi ogni riga cambia di uno spazio. Se confronti due versioni numerate con un diff, ecco perché l'intero file sembra modificato. Confronta piuttosto gli originali.

remove-line-numbers annulla sempre add-line-numbers?

No, ma le ragioni sono cambiate. Riconosce otto degli undici separatori — punto, parentesi chiusa, due punti, tabulazione, «[1] », «1] », «#1 » e «1 → » — e lascia di proposito il trattino, la barra verticale e lo spazio semplice, perché «10 - 20 people», «1 | Alice | 30» e «007 James» hanno la stessa forma e di solito sono contenuto. Con un separatore riconosciuto il viaggio di andata e ritorno è ora byte per byte, indentazione compresa: cinque righe di JavaScript con un corpo di funzione indentato di quattro e otto spazi sono entrate e tornate identiche, e lo stesso vale per YAML, Python e un listino piatto.

Ho passato lo strumento di rimozione su un listino e ne ha mangiato una parte. Cos'è successo?

Non può più farlo. Un tempo lo strumento cancellava le cifre iniziali seguite da un punto, una parentesi chiusa, due punti o una tabulazione, senza pretendere nulla dopo: così «3.14 is pi» diventava «14 is pi» e «12.50 Coffee» diventava «50 Coffee». Lo schema ora pretende uno spazio, o la fine della riga, dopo il separatore, e un punto decimale non è mai seguito da uno spazio: «3.14 is pi», «1.2.3 version» e «12.50 Coffee» tornano tutti intatti. Ciò che può ancora portarsi via è una riga con la forma esatta del suo stesso output — «2026. A year.» dà «A year.», «12: 30 departure» dà «30 departure» — e, da quando l'insieme dei marcatori si è allargato, i richiami di nota: «[1] See note» dà «See note». Un elenco separato da virgole è sicuro in ogni caso, perché la virgola non compare in nessuna forma di marcatore.

Devo numerare codice sorgente per una revisione del codice?

Di solito no, anche se non è più rischioso. Il codice porta già i numeri di riga ovunque venga letto — nel margine dell'editor, in un diff, nell'interfaccia di revisione di qualsiasi piattaforma — quindi numerarlo aggiunge soprattutto rumore. Il ritorno però ora lo regge: con un punto, una parentesi, due punti o una tabulazione, numerare un file indentato e togliere i numeri lo restituisce byte per byte, indentazione compresa, cosa che prima non accadeva. Tre separatori continuano a non essere mai rimossi — il trattino, la barra verticale e lo spazio semplice — quindi evitali se i numeri devono poi sparire. La numerazione si guadagna il posto su testi senza numeri propri, letti fuori da uno strumento che li fornisca: un contratto diffuso come documento, un file di sottotitoli discusso in una conversazione, un elenco di stringhe mandato a un traduttore. Se stai rivedendo codice e la piattaforma è fuori portata, citarlo in un blocco e riferirti a esso per nome di funzione resta la via più tranquilla.