Actualizado el 08 de febrero de 2026
Bienvenidos a la actualización de 2026 del Capítulo 2.1 de nuestro Curso Completo de YAML. En esta guía definitiva, vamos a profundizar en un aspecto fundamental pero a menudo subestimado: los Comentarios YAML en Home Assistant. Más allá de la sintaxis básica, exploraremos las mejores prácticas que transformarán tus archivos de configuración, mejorando drásticamente la legibilidad YAML y facilitando la colaboración en Home Assistant, un pilar clave para cualquier proyecto de domótica serio.
Si acabas de llegar, puedes consultar la página principal del curso o el temario completo del segundo capítulo sobre YAML avanzado.
¿Qué Son Exactamente los Comentarios en YAML?
En esencia, los comentarios en YAML son líneas de texto que el procesador del sistema ignora por completo. No tienen ningún efecto sobre la funcionalidad de tu configuración de Home Assistant. Su único propósito es servir como notas para los humanos que leen el código. En una configuración domótica YAML, que puede crecer hasta cientos o miles de líneas, estos comentarios se convierten en una herramienta indispensable para recordar el propósito de una automatización, explicar una elección de diseño o guiar a otros usuarios (¡o a tu «yo» del futuro!).
Sintaxis YAML para Comentarios: La Regla de la Almohadilla (#)
La sintaxis YAML para crear un comentario es increíblemente simple: todo lo que sigue al símbolo de la almohadilla (#) hasta el final de esa misma línea se considera un comentario.
Puedes tener comentarios que ocupan una línea completa o comentarios «en línea» que se colocan después de una línea de código. Veamos algunos ejemplos de comentarios YAML aplicados a un archivo de configuración de Home Assistant de 2026:
# --- SECCIÓN DE SENSORES MQTT ---
# Esta sección agrupa todos los sensores que reciben datos a través del broker MQTT.
# Para más información sobre la configuración del broker, ver la guía de Mosquitto.
sensor:
- platform: mqtt
name: "Temperatura del Salón"
state_topic: "tele/sonoff_th16/SENSOR"
value_template: "{{ value_json.AM2301.Temperature }}" # Extrae el valor de temperatura del JSON
unit_of_measurement: "°C"
device_class: temperature
# --- SECCIÓN DE AUTOMATIZACIONES DE CLIMATIZACIÓN ---
automation:
- alias: "Activar climatización por calor si la temperatura baja"
trigger:
platform: numeric_state
entity_id: sensor.temperatura_del_salon
below: 20 # Umbral crítico. Se decidió 20°C tras análisis de confort en invierno de 2025.
action:
- service: climate.set_hvac_mode
target:
entity_id: climate.termostato_salon
data:
hvac_mode: "heat"Como puedes observar, los comentarios aportan un contexto valioso que el propio código no puede ofrecer, como la justificación de por qué se eligió un umbral de temperatura específico.
Mejores Prácticas para Comentar en Home Assistant en 2026
Escribir comentarios es un arte. Un buen comentario puede ahorrar horas de depuración, mientras que un mal comentario puede confundir más que ayudar. Aquí te presento mis mejores prácticas, pulidas tras años gestionando configuraciones complejas:
- Comenta el «Porqué», no el «Qué»: El código ya dice qué hace. Un buen comentario explica por qué lo hace. Por ejemplo, en lugar de
# Esto es un sensor de temperatura(que es obvio), es mejor# Sensor de alta precisión para controlar el termostato principal. - Estructura tus Archivos Grandes: En archivos como
configuration.yamlo en paquetes (packages), usa «separadores» para crear secciones visuales. Esto mejora enormemente la navegación.#------------------------------------------------- # SECCIÓN DE ILUMINACIÓN #------------------------------------------------- light: # ... #------------------------------------------------- # SECCIÓN DE SEGURIDAD #------------------------------------------------- alarm_control_panel: # ... - Documenta los «Valores Mágicos»: Si usas un número o texto que no es inmediatamente obvio (como un puerto, un umbral o un token), explícalo. El ejemplo anterior con
below: 20es perfecto: la justificación del valor es crucial. - Mantén los Comentarios Actualizados: Un comentario obsoleto es peor que ningún comentario. Si cambias una lógica en tu automatización, asegúrate de actualizar también el comentario que la describe.
- Añade Metadatos: En configuraciones compartidas, es útil añadir información sobre el autor o la fecha del último cambio, especialmente en automatizaciones complejas.
# Autor: Carlos C. # Última modificación: 2026-02-08 # Motivo: Ajustado el retardo para evitar falsos positivos con el sensor de movimiento. - alias: "Apagar luz del pasillo tras 5 minutos" # ...
Herramientas Esenciales para Trabajar con Comentarios YAML
En 2026, trabajar con YAML a ciegas en un bloc de notas ya no es una opción eficiente. Para maximizar la productividad y asegurar la calidad de tu código y comentarios, te recomiendo estas herramientas:
Editores de Código con Soporte Avanzado
El estándar de facto es Visual Studio Code. Con la extensión oficial de Home Assistant, no solo obtienes autocompletado y validación de entidades, sino que la sintaxis de los comentarios se colorea de forma distinta, haciéndolos fáciles de identificar y leer. Si aún no lo usas, te recomiendo seguir esta guía para instalar y configurar Visual Studio Code para Home Assistant.
Linters y Validadores YAML
Un «linter» es una herramienta que analiza tu código en busca de errores de sintaxis y estilo. Herramientas como yamllint pueden configurarse para, por ejemplo, forzar que los comentarios no excedan una cierta longitud de línea, mejorando la legibilidad. La mayoría de estas funciones ya vienen integradas en la extensión de Home Assistant para VS Code, que validará tu archivo cada vez que lo guardes.
Generación Automática de Documentación
Para los usuarios más avanzados o aquellos que gestionan configuraciones para terceros, es posible usar formatos de comentario especiales (como Javadoc o DocStrings en programación) para generar documentación externa automáticamente. Aunque esto excede el uso típico de un usuario doméstico, demuestra el poder de los comentarios bien estructurados como fuente única de verdad para la documentación del sistema.
Conclusión: Los Comentarios como Pilar de un Home Assistant Sostenible
Hemos visto que los comentarios en YAML son mucho más que simples notas. Son una herramienta estratégica para garantizar la legibilidad, facilitar el mantenimiento y potenciar la colaboración en Home Assistant. Adoptar buenas prácticas de comentario desde el principio te ahorrará incontables horas en el futuro y convertirá tu configuración en un proyecto robusto y fácil de gestionar, sin importar lo complejo que llegue a ser.
Ahora que dominas el arte de documentar tu código, estás listo para seguir avanzando en nuestro curso de YAML.
Sígueme en YouTube
