Commenti YAML: come commentare e disattivare righe in YAML
Commenti YAML
Commenti YAML: sintassi, regole inline e alternative ai blocchi | We.Inc
Come commentare in YAML: la sintassi #, la regola dello spazio per i commenti inline, perché non esiste un commento a blocchi e uno strumento che commenta o ripristina molte righe insieme.
Un commento YAML inizia con un cancelletto (#) e prosegue fino alla fine della riga. Può stare su una riga a sé o dopo un valore, purché uno spazio lo separi dal valore. YAML non ha una sintassi per i commenti a blocchi, quindi commentare più righe significa mettere # all'inizio di ciascuna.
Dove # inizia un commento in YAML e dove no
Riga
Il # è un commento?
Perché
Sì
Inizia la riga
port: 5432 # default
Sì
Spazio prima del #
url: https://x.example/#top
No
Nessuno spazio prima del #, quindi fa parte del valore
color: "#4F98FB"
No
Dentro una stringa tra virgolette
tag: #blue
Sì
Il valore è vuoto (null) e il resto è un commento
I commenti sono il motivo principale per cui i team scelgono YAML invece di JSON per la configurazione, eppure è facile inciampare nelle regole. Incolla un file nello strumento qui sotto per commentare un intervallo di righe o ripristinarle, poi consulta il riferimento per i casi in cui un # diventa silenziosamente parte dei tuoi dati.
Incolla il tuo YAML nella casella, oppure modifica l'esempio.
Inserisci il numero della prima e dell'ultima riga che vuoi cambiare.
Premi Commenta per aggiungere # dopo l'indentazione di ogni riga, oppure Rimuovi commento per toglierlo.
Copia il risultato nel tuo file. Le righe vuote nell'intervallo restano invariate.
Tieni il # allineato al codice che disattiva. Le righe commentate alla stessa indentazione sono molto più facili da ripristinare in seguito.
Metti uno spazio dopo il # nelle tue note. Non è obbligatorio, ma rende facile distinguere il codice commentato dalle osservazioni.
Metti tra virgolette ogni valore che contiene un # da conservare, come i colori esadecimali, così una modifica successiva non può trasformarlo in un commento.
Ricorda che la maggior parte delle librerie scarta i commenti quando un file viene caricato e salvato di nuovo. Non conservare nulla di importante solo in un commento che gli strumenti riscrivono.
Domande frequenti
YAML ha commenti multiriga o a blocchi?
No. La specifica definisce solo commenti di riga che iniziano con #. Per disattivare un blocco, metti # davanti a ogni riga. La maggior parte degli editor lo fa per una selezione con una sola scorciatoia, e lo strumento in questa pagina lo fa per qualunque intervallo di righe.
Perché il mio commento è diventato parte del valore?
Un # inizia un commento solo quando è preceduto da uno spazio. In url: https://site.example/#faq il # segue una barra, quindi resta dentro la stringa. Aggiungi uno spazio prima del # se intendevi un commento.
I commenti vengono conservati quando YAML viene convertito in JSON?
No. I commenti sono un dettaglio di presentazione, non dati, e JSON non ha un posto dove metterli. La RFC 9512 segnala che i commenti vengono scartati quando YAML viene serializzato come JSON.
Posso commentare dentro un block scalar?
No. Dentro un blocco | o >, una riga che inizia con # è testo normale e diventa parte della stringa. I commenti funzionano solo fuori dalle righe di contenuto del blocco.
Qual è la scorciatoia per commentare YAML in un editor?
Dipende dall'editor, non da YAML. In Visual Studio Code il comando Toggle Line Comment è Ctrl+/ su Windows e Linux e Cmd+/ su macOS; gli altri editor impostano i propri tasti.
Commenti inline e la regola dello spazio
La specifica YAML dice che i commenti devono essere separati dagli altri token da spazi bianchi. Questa sola regola spiega quasi ogni sorpresa: un # attaccato al testo che lo precede è un dato, e un # dopo uno spazio è l'inizio di una nota.
Anche un tab conta come spazio bianco in questo caso, ma dato che i tab non sono ammessi per l'indentazione è più semplice usare spazi ovunque.
Documentare bene un file di configurazione
Scrivi commenti che spieghino perché un valore è impostato, non quello che dice già il nome della chiave. Una riga come # 5 retry perché l'API dei pagamenti va in timeout sotto carico risparmia alla persona successiva una ricerca nella cronologia.
Metti in cima un breve commento di intestazione che dica quale programma legge il file e dove sono documentate tutte le sue opzioni.
Pattern di commento che userai
Commenti su riga intera e inline
Un commento su riga intera spiega una sezione; un commento inline richiede almeno uno spazio prima del #.
Disattivare temporaneamente un blocco
Ogni riga del servizio disattivato ha il proprio #, mantenuto all'indentazione originale così può essere ripristinato in modo pulito.
Commenta righe YAML
Incolla del YAML, scegli un intervallo di righe e passa quelle righe da attive a commentate. L'indentazione viene mantenuta, così la struttura resta facile da leggere.