YAML tem exatamente um caractere de comentário: o símbolo de cerquilha. Todas as outras perguntas sobre comentários YAML — como abranger várias linhas, onde a cerquilha é proibida, por que seu comentário em linha truncou um valor, se os parsers preservam comentários — remetem a entender essa única regra e suas bordas. Este guia cobre tudo, da sintaxe básica a fluxos de trabalho de produção para remover e validar arquivos YAML comentados.
Fundamentos da sintaxe de comentários YAML
Em YAML, um comentário começa com um caractere `#` e se estende até o fim da linha. Tudo a partir de `#` em diante — apenas naquela linha — é ignorado pelo parser. Não há delimitadores de fechamento, nem sintaxe de comentário de bloco, nem forma de embutir um comentário no meio de um valor. Um caractere, uma regra, sem exceções.
O caractere de comentário e o espaço obrigatório
A especificação YAML tem uma nuance importante que pega muitos desenvolvedores: um comentário em linha deve ser precedido por pelo menos um caractere de espaço em branco. Uma `#` grudada diretamente a um caractere que não é espaço não é tratada como comentário — é interpretada como parte do valor escalar circundante. Isso importa principalmente ao adicionar comentários depois de valores na mesma linha.
- Comentário em linha correto: `timeout: 30 # seconds` - há espaço antes do `#`
- Comentário em linha incorreto: `timeout: 30# seconds` - sem espaço, `#` passa a fazer parte do valor
- Linha de comentário isolada: `# This whole line is a comment` - nenhum valor antes
- Comentário indentado: ` # Indented comment inside a block` - indentação é aceita
Warning
Sintaxe de comentário de relance
Estes são os três padrões válidos de posicionamento de comentários em YAML. Qualquer outra variação é idêntica a um destes ou inválida:
- Comentário no início da linha: `# comment text` - colocado na coluna 0 ou após espaços iniciais
- Comentário em linha após um escalar: `key: value # comment` - um ou mais espaços antes do `#`
- Comentário em linha após um item de lista: `- item # comment` - a mesma regra de espaço se aplica
Onde comentários são permitidos
Comentários são legais na grande maioria dos lugares de um documento YAML. Entender a pequena lista de locais onde não são ajuda a evitar erros de parsing confusos que não mencionam comentários em nada.
Posições permitidas
- Antes de qualquer par chave-valor: coloque comentários de documentação acima da chave em uma linha dedicada
- Depois de qualquer valor escalar na mesma linha: `retries: 3 # max attempts`
- Depois de um item de lista: `- production # primary environment`
- Depois de uma chave de mapeamento (sem valor ainda): `database: # configured below`
- Em linhas em branco entre blocos: use linhas de comentário livremente como separadores visuais
- No topo do arquivo: comentários de documentação em nível de arquivo são comuns em configs de Kubernetes e CI/CD
Os marcadores de início e fim de documento
Comentários também são válidos antes e depois dos marcadores de documento YAML `---` (início de documento) e `...` (fim de documento). Isso permite adicionar comentários de metadados em nível de arquivo antes do corpo do documento em fluxos YAML de múltiplos documentos.
| Local | Exemplo | Comentário permitido? |
|---|---|---|
| Linha isolada | # Full-line comment | ✓ Sim |
| Depois de valor escalar | key: value # note | ✓ Sim (espaço exigido) |
| Depois de item de lista | - item # note | ✓ Sim (espaço exigido) |
| Antes do início de documento | # Header\n--- | ✓ Sim |
| Dentro de string entre aspas | "Say # hello" | ✗ Não - # é literal |
| Dentro de escalar de bloco | |\n line # note | ✗ Não - # é literal |
| Dentro de sequência de fluxo | [a, b # note, c] | ✗ Não - erro de sintaxe |
| Dentro de mapeamento de fluxo | {a: 1 # note, b: 2} | ✗ Não confiável |
Note
Comentários de múltiplas linhas e bloco
YAML não tem sintaxe de comentário de bloco. Não há equivalente a `/* ... */`, nem heredoc `#!`, nem forma de abrir um comentário em uma linha e fechá-lo em outra. Para comentar várias linhas consecutivas, você deve prefixar cada linha individualmente com `#`.
Um comentário é um caractere de cerquilha seguido por caracteres que não incluem quebras de linha, e vai até - mas não inclui - a próxima quebra de linha. Um comentário é tratado como espaço em branco.
O padrão convencional de comentário de bloco
Linhas `#` consecutivas são interpretadas visualmente como um comentário de bloco, embora cada linha seja tecnicamente um comentário de linha independente. Essa é a convenção universal em arquivos YAML de todos os ecossistemas — Kubernetes, GitHub Actions, Docker Compose, Helm charts e pipelines de CI/CD usam este padrão:
- `# -----------------------------------------`
- `# Database configuration`
- `# Update connection strings before deploying`
- `# -----------------------------------------`
Atalhos de editor para comentar múltiplas linhas
Todos os principais editores de código suportam alternar comentários em várias linhas selecionadas em arquivos YAML. Selecione as linhas que quer comentar e use o atalho de alternância — o editor adiciona ou remove `#` do início de cada linha selecionada simultaneamente. Isso torna o comentário de múltiplas linhas em YAML tão rápido quanto em qualquer outra linguagem.
- VS Code: Ctrl+/ (Windows/Linux) ou Cmd+/ (macOS) - alterna # nas linhas selecionadas
- IDEs JetBrains (IntelliJ, PyCharm, GoLand): Ctrl+/ ou Cmd+/ - mesmo comportamento
- Vim/Neovim: modo bloco visual (Ctrl+V), selecione as linhas, I, digite #, Esc
- Emacs: M-; ou comment-region com um modo YAML instalado
- Sublime Text / TextMate: Ctrl+/ ou Cmd+/ - alterna # em todas as linhas selecionadas
Tip
Onde comentários quebram coisas
Comentários são seguros na maioria dos contextos YAML, mas há quatro situações específicas em que uma `#` mal colocada produzirá um erro silencioso de dados ou uma falha dura de parsing. Conhecê-las de antemão evita horas de depuração confusa.
Dentro de strings entre aspas
Uma `#` dentro de uma string com aspas simples ou duplas é sempre um caractere literal, nunca um comentário. `message: "Hello # world"` armazena a string `Hello # world`. Isso é correto e intencional. O problema surge com strings sem aspas: `message: Hello # world` armazena `Hello` e trata `# world` como comentário — truncando seu valor silenciosamente. Ponha aspas em qualquer valor de string sem aspas que legitimamente contenha uma `#`.
Dentro de escalares de bloco (literal | e dobrado >)
Dentro do conteúdo de um escalar de bloco — as linhas indentadas que seguem um indicador `|` ou `>` — o caractere `#` não tem significado especial. É tratado como um caractere literal e incluído na string. Não é possível comentar linhas dentro de um escalar de bloco. Se você precisar excluir conteúdo, deve removê-lo por completo em vez de comentá-lo.
Dentro de coleções de fluxo ([ ] e { })
Sequências e mapeamentos de fluxo são escritos em uma única linha. Colocar uma cerquilha dentro de uma coleção de fluxo é um erro de sintaxe ou produz um resultado de parsing inesperado, dependendo do parser. Se você precisar anotar itens individuais em uma coleção de fluxo, converta-a para estilo de bloco (um item por linha), onde comentários em linha funcionam corretamente.
Cerquilha solta sem espaço precedente
Como abordado na seção de fundamentos, uma `#` não precedida de espaço em branco não é reconhecida como comentário por parsers em conformidade com a spec. O valor `port: 8080#dev` é interpretado como a string `8080#dev`, não como o inteiro `8080` com um comentário. Sempre escreva `port: 8080 # dev` com o espaço.
Warning
Remover comentários para produção
Arquivos YAML voltados a desenvolvedores costumam ser bem comentados para fins de documentação. Esses mesmos arquivos podem precisar ser passados a APIs, ferramentas de implantação ou sistemas de gestão de configuração que rejeitam comentários ou adicionam sobrecarga desnecessária de parsing. Remover os comentários antes da transmissão é a solução limpa.
Quando você precisa remover comentários
- Endpoints de API que rejeitam YAML comentado - algumas APIs REST interpretam corpos de requisição YAML e falham com comentários
- Ciclos de serialização de config - carregar e regravar YAML com parsers padrão remove comentários silenciosamente
- Redução de ruído em diffs - ao revisar mudanças de config, diffs de YAML sem comentários focam nas mudanças reais de valor
- Otimização de tamanho de arquivo - manifestos de Kubernetes bem comentados podem ficar bem menores sem comentários
- Pipelines de processamento automatizado - scripts que transformam YAML frequentemente precisam de entrada limpa sem lógica de tratamento de comentários
Removedor de Comentários YAML
Cole qualquer documento YAML e remova todos os comentários instantaneamente - saída limpa pronta para copiar, baixar ou passar a uma API. Roda inteiramente no seu navegador sem uploads.
O que a remoção de comentários muda e não muda
Uma ferramenta correta de remoção de comentários remove apenas o texto do comentário — a `#` e tudo depois dela naquela linha — sem alterar valores, chaves, indentação ou estrutura. Linhas de comentário isoladas são substituídas por linhas em branco ou removidas por completo. O YAML resultante é interpretado de forma idêntica ao original para todos os valores de dados.
Note
Remoção via código (Python e Node.js)
Se você precisa remover comentários programaticamente como parte de um pipeline, a abordagem mais simples em qualquer biblioteca YAML padrão é um ciclo de carregar e gravar: interprete o YAML em uma estrutura de dados e imediatamente serialize de volta. Comentários são descartados ao carregar e nunca escritos ao gravar. A saída é YAML válido com dados idênticos, mas sem comentários. Em Python, `PyYAML` faz isso em duas linhas. No Node.js, `js-yaml` faz o mesmo.
Padrões de comentário YAML do mundo real
Arquivos YAML bem comentados seguem padrões consistentes que facilitam sua manutenção, revisão e transferência para outros membros da equipe. Esses padrões aparecem em manifestos do Kubernetes, workflows do GitHub Actions, arquivos do Docker Compose e arquivos values de charts Helm.
Comentários de cabeçalho de arquivo
Coloque um bloco de comentários bem no topo do arquivo para documentar seu propósito, responsável e qualquer contexto crítico que não seja óbvio apenas pelo conteúdo. Essa é prática padrão em manifestos do Kubernetes e playbooks do Ansible. O bloco de comentários tipicamente inclui o propósito do arquivo, a data da última modificação e um link para documentação ou tickets relacionados.
Comentários separadores de seção
Arquivos YAML longos — particularmente `docker-compose.yml` e `values.yaml` de Helm com dezenas de chaves de nível superior — se beneficiam de separadores visuais de seção que ajudam leitores a se orientar. Uma linha de `# -----------------------------------------------` ou `# === DATABASE CONFIG ===` antes de um grupo lógico de chaves é uma convenção amplamente adotada. Use o validador de âncoras e aliases YAML para verificar se suas âncoras e aliases estão corretos ao reestruturar arquivos muito comentados.
Documentação em linha para valores não óbvios
Comentários em linha são mais valiosos para valores que não se explicam por si mesmos — números mágicos, sobrescritas específicas de ambiente, valores em unidades não óbvias ou campos com interdependências. Um comentário como `timeout: 300 # seconds; must match nginx keepalive_timeout` é muito mais útil que o valor sozinho. Ao trabalhar com substituição de variáveis de ambiente em configs YAML, a ferramenta de pré-visualização de substituição de env YAML pode ajudar a verificar como os padrões comentados interagem com sobrescritas em runtime.
- Documente unidades: `memory: 512 # MB - increase to 1024 for production`
- Sinalize interdependências: `enabled: false # also disable in config/prod.yaml`
- Explique padrões: `workers: 4 # matches CPU core count on t3.medium`
- Avise sobre mudanças necessárias: `host: localhost # CHANGE before deploying`
- Referencie docs externas: `algorithm: RS256 # see RFC 7518, section 3.3`
Tip
Validar YAML comentado
Adicionar comentários a um arquivo YAML cria novas oportunidades de erros de sintaxe que não são imediatamente óbvios — uma `#` dentro de uma string sem aspas, um espaço faltando antes de um comentário em linha, ou um comentário acidental dentro de um escalar de bloco. Rodar um validador depois de editar um arquivo YAML comentado é um seguro rápido contra esses problemas.
O que o validador de YAML detecta
O validador de YAML interpreta seu documento conforme a especificação YAML 1.2 e reporta quaisquer erros de sintaxe com números de linha e coluna. Ele detecta comentários mal colocados, erros de indentação introduzidos ao adicionar linhas de comentário, chaves duplicadas e formatos escalares inválidos. Cole seu YAML diretamente — sem upload de arquivo, sem cadastro, e nada sai do seu navegador.
Validador de YAML
Valide qualquer documento YAML conforme a especificação YAML 1.2 - detecta erros de sintaxe relacionados a comentários, problemas de indentação e chaves duplicadas com números de linha precisos.
Detectando chaves duplicadas em arquivos anotados
Quando desenvolvedores comentam um par chave-valor e adicionam um substituto abaixo dele, chaves duplicadas são um resultado comum. Por exemplo: comentar `timeout: 30` e adicionar `timeout: 60` abaixo deixa a versão comentada inativa — mas se o comentário for removido acidentalmente ou o arquivo for processado por uma ferramenta que remove comentários, a duplicata se torna ativa e o valor menor vence silenciosamente (ou gera erro, dependendo do parser). O detector de chaves duplicadas YAML detecta esses casos antes que causem problemas.
Convertendo entre formatos com comentários intactos
Se você está convertendo JSON para YAML com o conversor de JSON para YAML, saiba que a saída não conterá comentários — JSON não tem sintaxe de comentários, então não há comentários a transportar. Quaisquer comentários de documentação que você queira na saída YAML devem ser adicionados manualmente após a conversão. De modo similar, a ferramenta de mesclagem YAML pode afetar o posicionamento de comentários em arquivos mesclados, dependendo de como a mesclagem é feita.
Comparando configs YAML antes e depois de edições
Ao revisar mudanças em configurações YAML comentadas — particularmente em pull requests — o destacador de diff para configs JSON/YAML evidencia mudanças significativas de valor separadamente de edições apenas de comentários. Isso torna a revisão de código mais rápida e reduz o risco de aprovar uma mudança acidental de valor enterrada em um diff cheio de atualizações de comentários.
Key takeaways
- YAML usa um único caractere de comentário: `#`. Tudo do `#` até o fim da linha é um comentário.
- Comentários em linha exigem um espaço antes do `#` - escrever `value# comment` sem o espaço é um erro de sintaxe ou produz um valor inesperado.
- YAML não tem sintaxe de comentário de bloco - comente várias linhas prefixando cada uma individualmente com `#`.
- Uma `#` dentro de strings entre aspas e escalares de bloco é sempre um caractere literal, nunca um comentário.
- Comentários são invisíveis para os parsers - são descartados ao carregar e não podem ser recuperados por PyYAML, js-yaml ou qualquer biblioteca padrão.
- Use o removedor de comentários YAML para remover comentários antes de passar YAML a APIs ou ferramentas de implantação.
- Sempre valide com o validador de YAML depois de adicionar comentários em linha para detectar bugs silenciosos de truncamento de valores.