Comentários em YAML: como comentar e desativar trechos de YAML
Comentários em YAML
Comentários em YAML: sintaxe, regras inline e alternativas ao bloco | We.Inc
Como comentar em YAML: a sintaxe #, a regra do espaço em comentários inline, por que não existe comentário em bloco e uma ferramenta que comenta ou restaura várias linhas de uma vez.
Um comentário YAML começa com o sinal de cerquilha (#) e vai até o fim da linha. Ele pode ficar em uma linha própria ou depois de um valor, desde que haja um espaço em branco separando-o do valor. YAML não tem sintaxe de comentário em bloco, então comentar várias linhas significa colocar # no início de cada uma.
Onde # inicia um comentário em YAML e onde não inicia
Linha
O # é um comentário?
Por quê
Sim
Começa a linha
port: 5432 # default
Sim
Há espaço em branco antes do #
url: https://x.example/#top
Não
Não há espaço em branco antes do #, então ele faz parte do valor
color: "#4F98FB"
Não
Está dentro de uma string entre aspas
tag: #blue
Sim
O valor fica vazio (null) e o resto é comentário
Comentários são o principal motivo para os times escolherem YAML em vez de JSON na configuração, mas é fácil tropeçar nas regras. Cole um arquivo na ferramenta abaixo para comentar ou restaurar um intervalo de linhas e depois confira a referência dos casos em que um # vira, sem aviso, parte dos seus dados.
Cole o seu YAML na caixa ou edite o exemplo.
Informe os números da primeira e da última linha que você quer alterar.
Clique em Comentar para adicionar # depois da indentação de cada linha, ou em Descomentar para removê-lo.
Copie o resultado de volta para o seu arquivo. Linhas em branco no intervalo não são alteradas.
Mantenha o # alinhado com o código que ele desativa. Linhas comentadas na mesma indentação são muito mais fáceis de restaurar depois.
Coloque um espaço depois do # nas suas próprias notas. Não é obrigatório, mas facilita distinguir código comentado de observações.
Coloque entre aspas qualquer valor com um # que você quer manter, como cores hexadecimais, para que uma edição futura não o transforme em comentário.
Lembre que a maioria das bibliotecas descarta os comentários quando um arquivo é carregado e salvo de novo. Não guarde nada importante só em um comentário que as ferramentas reescrevem.
Perguntas frequentes
YAML tem comentários de várias linhas ou em bloco?
Não. A especificação só define comentários de linha que começam com #. Para desativar um bloco, coloque # no início de cada linha. A maioria dos editores faz isso para uma seleção com um único atalho, e a ferramenta desta página faz isso para qualquer intervalo de linhas.
Por que o meu comentário virou parte do valor?
Um # só inicia um comentário quando há espaço em branco antes dele. Em url: https://site.example/#faq o # vem depois de uma barra, então continua dentro da string. Adicione um espaço antes do # se a intenção era um comentário.
Os comentários são mantidos quando YAML é convertido para JSON?
Não. Comentários são um detalhe de apresentação, não dados, e o JSON não tem onde colocá-los. A RFC 9512 observa que os comentários são descartados quando o YAML é serializado como JSON.
Posso comentar dentro de um block scalar?
Não. Dentro de um bloco | ou >, uma linha que começa com # é texto comum e vira parte da string. Comentários só funcionam fora das linhas de conteúdo do bloco.
Qual é o atalho para comentar YAML em um editor?
Ele é do editor, não do YAML. No Visual Studio Code, o comando Toggle Line Comment é Ctrl+/ no Windows e no Linux e Cmd+/ no macOS; outros editores definem as próprias teclas.
Comentários inline e a regra do espaço
A especificação YAML diz que os comentários precisam estar separados dos outros tokens por espaço em branco. Essa única regra explica quase todas as surpresas: um # colado no texto anterior é dado, e um # depois de um espaço é o início de uma nota.
Um tab também conta como espaço em branco aqui, mas como tabs não são permitidos na indentação, é mais simples usar espaços em todo lugar.
Documentando bem um arquivo de configuração
Escreva comentários que digam por que um valor foi definido, não o que o nome da chave já diz. Uma linha como # 5 tentativas porque a API de pagamento estoura o tempo sob carga poupa a próxima pessoa de vasculhar o histórico.
Coloque um comentário curto de cabeçalho no topo dizendo qual programa lê o arquivo e onde as opções completas estão documentadas.
Padrões de comentário que você vai usar
Comentários de linha inteira e inline
Um comentário de linha inteira explica uma seção; um comentário inline precisa de pelo menos um espaço antes do #.
Desativando um bloco temporariamente
Cada linha do serviço desativado leva o próprio #, mantido na indentação original para que possa ser restaurado sem problemas.
Comente linhas de YAML
Cole YAML, escolha um intervalo de linhas e alterne essas linhas entre ativas e comentadas. A indentação é preservada, então a estrutura continua fácil de ler.