YAML tiene exactamente un carácter de comentario: el símbolo de almohadilla. Todas las demás preguntas sobre comentarios YAML — cómo abarcar varias líneas, dónde la almohadilla está prohibida, por qué tu comentario en línea truncó un valor, si los parsers preservan los comentarios — se remontan a entender esa única regla y sus bordes. Esta guía cubre todo, desde la sintaxis básica hasta flujos de trabajo de producción para eliminar y validar archivos YAML comentados.
Fundamentos de la sintaxis de comentarios YAML
En YAML, un comentario comienza con un carácter `#` y se extiende hasta el final de la línea. Todo desde `#` en adelante — solo en esa línea — es ignorado por el parser. No hay delimitadores de cierre, ni sintaxis de comentario de bloque, ni forma de incrustar un comentario en medio de un valor. Un carácter, una regla, sin excepciones.
El carácter de comentario y el espacio obligatorio
La especificación YAML tiene un matiz importante que confunde a muchos desarrolladores: un comentario en línea debe ir precedido por al menos un carácter de espacio en blanco. Una `#` pegada directamente a un carácter que no es espacio no se trata como comentario — se parsea como parte del valor escalar circundante. Esto importa sobre todo al añadir comentarios después de valores en la misma línea.
- Comentario en línea correcto: `timeout: 30 # seconds` - hay espacio antes de `#`
- Comentario en línea incorrecto: `timeout: 30# seconds` - sin espacio, `#` pasa a formar parte del valor
- Línea de comentario independiente: `# This whole line is a comment` - sin valor antes
- Comentario indentado: ` # Indented comment inside a block` - la indentación es válida
Warning
Sintaxis de comentario de un vistazo
Estos son los tres patrones válidos de colocación de comentarios en YAML. Cualquier otra variación es idéntica a una de estas o inválida:
- Comentario al inicio de línea: `# comment text` - colocado en la columna 0 o tras espacios iniciales
- Comentario en línea tras un escalar: `key: value # comment` - uno o más espacios antes de `#`
- Comentario en línea tras un elemento de lista: `- item # comment` - se aplica la misma regla de espacio
Dónde se permiten los comentarios
Los comentarios son legales en la gran mayoría de lugares de un documento YAML. Entender la escasa lista de ubicaciones donde no lo son te ayuda a evitar errores de parseo confusos que no mencionan comentarios en absoluto.
Posiciones permitidas
- Antes de cualquier par clave-valor: coloca comentarios de documentación sobre la clave en una línea dedicada
- Después de cualquier valor escalar en la misma línea: `retries: 3 # max attempts`
- Después de un elemento de lista: `- production # primary environment`
- Después de una clave de mapeo (sin valor aún): `database: # configured below`
- En líneas en blanco entre bloques: usa líneas de comentario libremente como separadores visuales
- En la parte superior del archivo: los comentarios de documentación a nivel de archivo son comunes en configs de Kubernetes y CI/CD
Los marcadores de inicio y fin de documento
Los comentarios también son válidos antes y después de los marcadores de documento YAML `---` (inicio de documento) y `...` (fin de documento). Esto permite añadir comentarios de metadatos a nivel de archivo antes del cuerpo del documento en flujos YAML de múltiples documentos.
| Ubicación | Ejemplo | ¿Comentario permitido? |
|---|---|---|
| Línea independiente | # Full-line comment | ✓ Sí |
| Tras valor escalar | key: value # note | ✓ Sí (espacio requerido) |
| Tras elemento de lista | - item # note | ✓ Sí (espacio requerido) |
| Antes del inicio de documento | # Header\n--- | ✓ Sí |
| Dentro de cadena entrecomillada | "Say # hello" | ✗ No - # es literal |
| Dentro de escalar de bloque | |\n line # note | ✗ No - # es literal |
| Dentro de secuencia de flujo | [a, b # note, c] | ✗ No - error de sintaxis |
| Dentro de mapeo de flujo | {a: 1 # note, b: 2} | ✗ Poco fiable |
Note
Comentarios multilínea y de bloque
YAML no tiene sintaxis de comentario de bloque. No hay equivalente a `/* ... */`, ni heredoc `#!`, ni forma de abrir un comentario en una línea y cerrarlo en otra. Para comentar varias líneas consecutivas, debes prefijar cada línea individualmente con `#`.
Un comentario es un carácter de almohadilla seguido de caracteres que no incluyen saltos de línea, y llega hasta - sin incluir - el siguiente salto de línea. Un comentario se trata como espacio en blanco.
El patrón convencional de comentario de bloque
Las líneas consecutivas con `#` se interpretan visualmente como un comentario de bloque, aunque cada línea sea técnicamente un comentario independiente de una línea. Es la convención universal en archivos YAML de todos los ecosistemas — Kubernetes, GitHub Actions, Docker Compose, Helm charts y pipelines de CI/CD usan este patrón:
- `# -----------------------------------------`
- `# Database configuration`
- `# Update connection strings before deploying`
- `# -----------------------------------------`
Atajos de editor para comentarios multilínea
Cada editor de código importante soporta alternar comentarios en varias líneas seleccionadas en archivos YAML. Selecciona las líneas que quieres comentar y usa el atajo de alternancia — el editor añade o quita `#` al inicio de cada línea seleccionada simultáneamente. Esto hace que comentar varias líneas en YAML sea tan rápido como en cualquier otro lenguaje.
- VS Code: Ctrl+/ (Windows/Linux) o Cmd+/ (macOS) - alterna # en las líneas seleccionadas
- IDEs de JetBrains (IntelliJ, PyCharm, GoLand): Ctrl+/ o Cmd+/ - mismo comportamiento
- Vim/Neovim: modo bloque visual (Ctrl+V), selecciona líneas, I, escribe #, Esc
- Emacs: M-; o comment-region con un modo YAML instalado
- Sublime Text / TextMate: Ctrl+/ o Cmd+/ - alterna # en todas las líneas seleccionadas
Tip
Dónde los comentarios rompen cosas
Los comentarios son seguros en la mayoría de contextos YAML, pero hay cuatro situaciones específicas donde una `#` mal colocada producirá un error de datos silencioso o un fallo duro de parseo. Conocerlas de antemano evita horas de depuración confusa.
Dentro de cadenas entrecomilladas
Una `#` dentro de una cadena con comillas simples o dobles es siempre un carácter literal, nunca un comentario. `message: "Hello # world"` almacena la cadena `Hello # world`. Esto es correcto e intencional. El problema surge con cadenas sin comillas: `message: Hello # world` almacena `Hello` y trata `# world` como comentario — truncando tu valor silenciosamente. Entrecomilla cualquier valor de cadena sin comillas que legítimamente contenga una `#`.
Dentro de escalares de bloque (literal | y plegado >)
Dentro del contenido de un escalar de bloque — las líneas indentadas que siguen a un indicador `|` o `>` — el carácter `#` no tiene significado especial. Se trata como un carácter literal y se incluye en la cadena. No puedes comentar líneas dentro de un escalar de bloque. Si necesitas excluir contenido, debes eliminarlo por completo en lugar de comentarlo.
Dentro de colecciones de flujo ([ ] y { })
Las secuencias y mapeos de flujo se escriben en una sola línea. Colocar una almohadilla dentro de una colección de flujo es un error de sintaxis o produce un resultado de parseo inesperado según el parser. Si necesitas anotar elementos individuales de una colección de flujo, conviértela a estilo de bloque (un elemento por línea) donde los comentarios en línea funcionan correctamente.
Almohadilla sola sin espacio previo
Como se cubrió en la sección de fundamentos, una `#` no precedida de espacio en blanco no se reconoce como comentario por los parsers conformes a la especificación. El valor `port: 8080#dev` se parsea como la cadena `8080#dev`, no como el entero `8080` con un comentario. Escribe siempre `port: 8080 # dev` con el espacio.
Warning
Eliminar comentarios para producción
Los archivos YAML orientados a desarrolladores suelen estar muy comentados con fines de documentación. Esos mismos archivos pueden necesitar pasarse a APIs, herramientas de despliegue o sistemas de gestión de configuración que rechacen los comentarios o añadan sobrecarga innecesaria de parseo. Eliminar los comentarios antes de la transmisión es la solución limpia.
Cuándo necesitas eliminar comentarios
- Endpoints de API que rechazan YAML comentado - algunas APIs REST parsean cuerpos de petición YAML y fallan con comentarios
- Ciclos de serialización de config - cargar y re-volcar YAML con parsers estándar elimina los comentarios silenciosamente
- Reducción de ruido en diffs - al revisar cambios de config, los diffs de YAML sin comentarios se centran en los cambios reales de valor
- Optimización de tamaño de archivo - los manifiestos de Kubernetes muy comentados pueden ser notablemente más pequeños sin comentarios
- Pipelines de procesamiento automatizado - los scripts que transforman YAML a menudo necesitan entrada limpia sin lógica de manejo de comentarios
Eliminador de Comentarios YAML
Pega cualquier documento YAML y elimina todos los comentarios al instante - salida limpia lista para copiar, descargar o pasar a una API. Se ejecuta enteramente en tu navegador sin subidas.
Qué cambia y qué no cambia la eliminación de comentarios
Una herramienta correcta de eliminación de comentarios remueve solo el texto del comentario — la `#` y todo lo que le sigue en esa línea — sin alterar valores, claves, indentación ni estructura. Las líneas de comentario independientes se reemplazan por líneas en blanco o se eliminan por completo. El YAML resultante parsea de forma idéntica al original para todos los valores de datos.
Note
Eliminación mediante código (Python y Node.js)
Si necesitas eliminar comentarios programáticamente como parte de un pipeline, el enfoque más simple en cualquier librería YAML estándar es un ciclo de cargar y volcar: parsea el YAML a una estructura de datos y serialízalo de vuelta inmediatamente. Los comentarios se descartan al cargar y nunca se escriben al volcar. La salida es YAML válido con datos idénticos pero sin comentarios. En Python, `PyYAML` lo hace en dos líneas. En Node.js, `js-yaml` hace lo mismo.
Patrones de comentario YAML del mundo real
Los archivos YAML bien comentados siguen patrones consistentes que facilitan su mantenimiento, revisión y traspaso a otros miembros del equipo. Estos patrones aparecen en manifiestos de Kubernetes, workflows de GitHub Actions, archivos de Docker Compose y archivos values de charts de Helm.
Comentarios de encabezado de archivo
Coloca un bloque de comentarios en la parte superior del archivo para documentar su propósito, responsable y cualquier contexto crítico que no sea obvio solo con el contenido. Es práctica estándar en manifiestos de Kubernetes y playbooks de Ansible. El bloque de comentarios típicamente incluye el propósito del archivo, la fecha de última modificación y un enlace a documentación o tickets relacionados.
Comentarios separadores de sección
Los archivos YAML largos — en particular `docker-compose.yml` y los `values.yaml` de Helm con docenas de claves de nivel superior — se benefician de separadores visuales de sección que ayudan a los lectores a orientarse. Una línea de `# -----------------------------------------------` o `# === DATABASE CONFIG ===` antes de un grupo lógico de claves es una convención ampliamente adoptada. Usa el validador de anclas y aliases de YAML para comprobar que tus anclas y aliases son correctos al reestructurar archivos muy comentados.
Documentación en línea para valores no obvios
Los comentarios en línea son más valiosos para valores que no se explican por sí mismos — números mágicos, anulaciones específicas de entorno, valores en unidades no obvias o campos con interdependencias. Un comentario como `timeout: 300 # seconds; must match nginx keepalive_timeout` es mucho más útil que el valor solo. Al trabajar con sustitución de variables de entorno en configs YAML, la herramienta de vista previa de sustitución de env de YAML puede ayudarte a verificar cómo interactúan los valores por defecto comentados con las anulaciones en runtime.
- Documenta unidades: `memory: 512 # MB - increase to 1024 for production`
- Señala interdependencias: `enabled: false # also disable in config/prod.yaml`
- Explica valores por defecto: `workers: 4 # matches CPU core count on t3.medium`
- Advierte de cambios necesarios: `host: localhost # CHANGE before deploying`
- Referencia documentación externa: `algorithm: RS256 # see RFC 7518, section 3.3`
Tip
Validar YAML comentado
Añadir comentarios a un archivo YAML crea nuevas oportunidades de errores de sintaxis que no son inmediatamente obvios — una `#` dentro de una cadena sin comillas, un espacio faltante antes de un comentario en línea, o un comentario accidental dentro de un escalar de bloque. Ejecutar un validador después de editar un archivo YAML comentado es un seguro rápido contra estos problemas.
Qué detecta el validador de YAML
El validador de YAML parsea tu documento contra la especificación YAML 1.2 e informa de cualquier error de sintaxis con números de línea y columna. Detecta comentarios mal colocados, errores de indentación introducidos al añadir líneas de comentario, claves duplicadas y formatos escalares inválidos. Pega tu YAML directamente — sin subida de archivos, sin registro y nada sale de tu navegador.
Validador de YAML
Valida cualquier documento YAML contra la especificación YAML 1.2 - detecta errores de sintaxis relacionados con comentarios, problemas de indentación y claves duplicadas con números de línea precisos.
Detectar claves duplicadas en archivos anotados
Cuando los desarrolladores comentan un par clave-valor y añaden un reemplazo debajo, las claves duplicadas son un resultado común. Por ejemplo: comentar `timeout: 30` y añadir `timeout: 60` debajo deja la versión comentada inactiva — pero si el comentario se elimina accidentalmente o el archivo es procesado por una herramienta que elimina comentarios, el duplicado se activa y el valor inferior gana silenciosamente (o da error, según el parser). El detector de claves duplicadas de YAML los detecta antes de que causen problemas.
Convertir entre formatos con comentarios intactos
Si estás convirtiendo JSON a YAML con el convertidor de JSON a YAML, ten en cuenta que la salida no contendrá comentarios — JSON no tiene sintaxis de comentarios, así que no hay comentarios que trasladar. Cualquier comentario de documentación que quieras en la salida YAML debe añadirse manualmente tras la conversión. De manera similar, la herramienta de fusión de YAML puede afectar la colocación de comentarios en archivos fusionados según cómo se realice la fusión.
Comparar configs YAML antes y después de editar
Al revisar cambios en configuraciones YAML comentadas — particularmente en pull requests — el resaltador de diffs para configs JSON/YAML muestra los cambios de valor significativos por separado de las ediciones de solo comentarios. Esto hace la revisión de código más rápida y reduce el riesgo de aprobar un cambio accidental de valor enterrado en un diff lleno de actualizaciones de comentarios.
Key takeaways
- YAML usa un único carácter de comentario: `#`. Todo desde `#` hasta el final de la línea es un comentario.
- Los comentarios en línea requieren un espacio antes de `#` - escribir `value# comment` sin el espacio es un error de sintaxis o produce un valor inesperado.
- YAML no tiene sintaxis de comentario de bloque - comenta varias líneas prefijando cada una individualmente con `#`.
- Una `#` dentro de cadenas entrecomilladas y escalares de bloque es siempre un carácter literal, nunca un comentario.
- Los comentarios son invisibles para los parsers - se descartan al cargar y no pueden recuperarse con PyYAML, js-yaml ni ninguna librería estándar.
- Usa el eliminador de comentarios YAML para eliminar comentarios antes de pasar YAML a APIs o herramientas de despliegue.
- Valida siempre con el validador de YAML después de añadir comentarios en línea para detectar bugs silenciosos de truncamiento de valores.