Actualizado el 29 de enero de 2026
En el mundo del desarrollo y la automatización, dominar la configuración es clave. Archivos en formato YAML son el estándar de facto en herramientas como Home Assistant, Kubernetes o Docker Compose. Mantener estos archivos limpios y legibles es fundamental, y aunque muchos buscan el término «anotaciones en YAML», la herramienta correcta y oficial para esta tarea son los comentarios en YAML. Un comentario bien puesto puede ahorrar horas de depuración a tu «yo» del futuro o a tus compañeros de equipo.
Este artículo es la guía definitiva de 2026 sobre cómo usar comentarios en YAML de manera efectiva. Exploraremos desde la sintaxis básica hasta las buenas prácticas que marcan la diferencia en proyectos complejos, con ejemplos claros y aplicables hoy mismo.
¿Qué son realmente los Comentarios en YAML y por qué son cruciales?
Para ser claros desde el principio: YAML como lenguaje no tiene una característica específica llamada «anotaciones» como las que se pueden encontrar en lenguajes de programación como Java o Python. Cuando la gente habla de «anotaciones», en el 99% de los casos se refiere a los comentarios.
Un comentario es una porción de texto dentro de un archivo YAML que el procesador (o parser) ignora por completo. Su único propósito es ser leído por humanos para proporcionar contexto, explicaciones o documentación directamente en el código. Son esenciales por varias razones:
- Claridad: Explican el «porqué» de una configuración, no solo el «qué».
- Mantenimiento: Facilitan que otros (o tú mismo meses después) entiendan y modifiquen el archivo sin romper nada.
- Depuración: Permiten deshabilitar temporalmente bloques de código («comentar») para aislar problemas.
Sintaxis YAML: Cómo Escribir Comentarios
La sintaxis YAML para los comentarios es extremadamente sencilla y se basa en un único carácter: la almohadilla (#).
Comentarios de una Sola Línea
Cualquier texto que siga a una almohadilla (#) en una línea es considerado un comentario y será ignorado. Puede ocupar su propia línea o ir al final de una línea de código.
# Este es un comentario que ocupa toda la línea.
# Es útil para describir el bloque de código que viene a continuación.
clave_configuracion: valor # Este es un comentario al final de una línea. Explica esta clave específica.YAML Multilínea: ¿Cómo se comenta?
Una pregunta frecuente es cómo crear comentarios multilínea. A diferencia de otros formatos como CSS o JavaScript que usan /* ... */, YAML no tiene una sintaxis de bloque para comentarios. Para crear un comentario que abarque varias líneas, simplemente debes empezar cada línea con el símbolo de almohadilla (#).
# Este es un comentario más largo que necesita
# dividirse en varias líneas para mantener una
# buena legibilidad en el archivo de configuración.
automation:
- alias: "Mi automatización"
# ... resto de la configuraciónBuenas Prácticas para Comentar en YAML en 2026
Escribir comentarios es fácil, pero escribir buenos comentarios es un arte. Aquí te dejo mis buenas prácticas YAML recomendadas, pulidas tras años de trabajo con infraestructuras complejas:
- Comenta el «porqué», no el «qué»: El código ya muestra qué hace. Un buen comentario explica por qué se tomó esa decisión.
❌ Mal:timeout: 300 # Establece el timeout a 300 segundos.
✅ Bien:timeout: 300 # Aumentado a 300s para evitar fallos en conexiones lentas con la API externa. - Mantén los comentarios actualizados: Un comentario obsoleto que describe un comportamiento que ya no existe es peor que no tener ningún comentario. Si cambias el código, revisa el comentario.
- Usa comentarios para separar bloques lógicos: En archivos largos, úsalos como títulos para mejorar la navegación.
#----------------------------------# # CONFIGURACIÓN DE BASE DE DATOS # #----------------------------------# database: host: postgres.local #----------------------------------# # CONFIGURACIÓN DEL SERVIDOR WEB # #----------------------------------# webserver: port: 8080 - Documenta valores «mágicos»: Si usas un número, una cadena de texto o un booleano cuyo significado no es obvio a primera vista, explícalo.
- Utiliza comentarios para desactivar código: En lugar de borrar una sección que quizás necesites más tarde, simplemente coméntala. Es la forma más rápida y segura de probar cambios.
Ejemplos YAML Prácticos en Diferentes Plataformas
Los comentarios son universales en YAML, pero su contexto cambia según la herramienta. Veamos algunos ejemplos YAML del mundo real.
Home Assistant YAML
En Home Assistant, los comentarios son vitales para recordar para qué sirve cada automatización o qué dispositivo estás configurando, sobre todo cuando trabajas con integraciones complejas como Zigbee2MQTT en Home Assistant 2026.
# --- Automatización del Salón ---
# Objetivo: Encender la luz principal del salón cuando se detecta movimiento
# y el sol ya se ha puesto. Se apaga tras 5 minutos sin movimiento.
automation:
- alias: "Encender luz del salón por movimiento al anochecer"
trigger:
# Disparador: Sensor de movimiento del salón
- platform: state
entity_id: binary_sensor.movimiento_salon
to: 'on'
condition:
# Condición: Solo si es de noche
- condition: state
entity_id: sun.sun
state: 'below_horizon'
action:
# Acción: Encender la luz
- service: light.turn_on
target:
entity_id: light.luz_principal_salon
Docker Compose
En Docker, los comentarios ayudan a explicar la función de cada servicio, los puertos expuestos o la persistencia de los volúmenes.
version: '3.8'
services:
web:
image: nginx:latest
ports:
# Expone el puerto 80 del contenedor al puerto 8080 del host
- "8080:80"
volumes:
# Monta el contenido local en el directorio web del contenedor
- ./website:/usr/share/nginx/html
db:
image: postgres:15
environment:
# Las credenciales se cargan desde un archivo .env para mayor seguridad
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
GitHub Actions (CI/CD)
En los flujos de trabajo de CI/CD, los comentarios son cruciales para describir los pasos, las condiciones de ejecución y las variables de entorno utilizadas.
name: CI Pipeline
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
# Paso 1: Descargar el código del repositorio
- uses: actions/checkout@v4
# Paso 2: Configurar el entorno de Node.js
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
# Paso 3: Instalar dependencias y ejecutar tests
- name: Install and Test
run: |
npm install
npm test
Más Allá de los Comentarios: Anclas y Alias para Organizar tu Código
Aunque no son comentarios, las anclas (&) y alias (*) son otra herramienta de YAML para mejorar la legibilidad y reducir la duplicación. Te permiten definir un bloque de código una vez y reutilizarlo en múltiples lugares.
Si te interesa profundizar en esta técnica avanzada para optimizar tus archivos, te recomiendo leer mi guía completa sobre anclas y alias en YAML.
# Definimos un ancla con la configuración base para los reintentos
default_retries: &default_retries
count: 3
delay: 5s
job1:
# Usamos el alias para insertar la configuración
retries: *default_retries
script: "do_something.sh"
job2:
# La volvemos a usar aquí
retries: *default_retries
script: "do_another_thing.sh"
Herramientas Modernas (2026) para Validar y Formatear YAML
En 2026, ya no hay excusa para trabajar con archivos YAML mal formateados. Existen herramientas excelentes que nos ayudan a mantener la calidad del código:
- Linters (Validadores): El más popular es
yamllint. Es una herramienta de línea de comandos que puedes integrar en tus pipelines de CI/CD para verificar automáticamente que los archivos YAML cumplen con las reglas de sintaxis y estilo (longitud de línea, indentación, etc.). - Extensiones para Editores de Código: Si usas Visual Studio Code, la extensión «YAML» de Red Hat es imprescindible. Ofrece validación en tiempo real, autocompletado, formateo automático y detección de errores mientras escribes. Otros IDEs como los de la familia JetBrains también ofrecen un soporte excelente.
Para conocer más opciones, puedes consultar mi artículo sobre las mejores herramientas para trabajar con YAML.
En resumen, los comentarios en YAML son mucho más que simples notas. Son una herramienta fundamental para la colaboración, el mantenimiento y la legibilidad de cualquier proyecto que dependa de este formato. Adoptar buenas prácticas de comentario y apoyarse en las herramientas modernas no es una opción, sino una necesidad para cualquier profesional que trabaje con la tecnología actual.