Comentarios YAML Home Assistant: Guía Completa 2026

Revisión técnica: 27 de octubre de 2026. Esta es una guía complementaria procedente del curso anterior, no un capítulo numerado del nuevo. Para seguir el itinerario, consulta el curso actual de YAML en Home Assistant.

Esta guía complementaria explica los comentarios YAML en Home Assistant: cómo documentar decisiones, mejorar la legibilidad y mantener notas útiles sin confundir comentarios con datos o expresiones Jinja.

Para seguir el itinerario actual, consulta el curso de YAML en Home Assistant. Esta página no es el capítulo 2.1 de ese curso nuevo.

¿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 (#)

Un comentario empieza con # fuera de una cadena entre comillas y del contenido de un escalar; un comentario al final de una línea debe estar separado del valor anterior. Una almohadilla dentro de comillas, o dentro del contenido de un escalar de bloque, es un dato, no un comentario YAML.

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:

# Fragmento de configuration.yaml: adapta claves existentes y entidades reales
mqtt:
  sensor:
    - name: "Temperatura del Salón"
      state_topic: "tele/sonoff_th16/SENSOR"
      value_template: "{{ value_json.AM2301.Temperature }}" # Extrae la temperatura del mensaje del dispositivo
      unit_of_measurement: "°C"
      device_class: temperature

automation:
  - alias: "Pedir calefacción por debajo del umbral de confort"
    triggers:
      - trigger: numeric_state
        entity_id: sensor.temperatura_del_salon
        below: 20 # Umbral de confort de ejemplo; adáptalo a tu vivienda
    actions:
      - action: 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.yaml o 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: 20 es 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.

Almohadillas, notas multilínea y comentarios Jinja

# Dos líneas de comentario necesitan dos almohadillas
# YAML no usa comentarios /* ... */
color: "#FF5733"
mensaje: |
  # Esta línea es contenido del mensaje, no un comentario YAML

Este fragmento ilustra YAML genérico, no una configuración completa de Home Assistant. Dentro de una plantilla Jinja se utiliza {# un comentario Jinja #}. Una almohadilla dentro de un escalar de bloque YAML no desactiva una acción ni oculta ese texto en el mensaje resultante.

Desactivar un bloque sin dejar una estructura inválida

Comenta todas las líneas pertinentes, no solo el encabezado o la primera clave. Dejar hijos sueltos puede cambiar la estructura o producir un error de validación. Para una prueba temporal, considera desactivar la automatización con sus propios controles en lugar de comentar fragmentos arbitrarios de archivos gestionados. Comprueba la indentación y valida después.

Comentarios, anotaciones y privacidad

Una nota para una persona es un comentario. Una anotación específica de una plataforma, como los metadatos de Kubernetes, es un dato real y no se sustituye por un comentario. No guardes contraseñas ni tokens en comentarios: siguen presentes al compartir el archivo. Prefiere herramientas locales o ejemplos anonimizados a subir configuraciones privadas a validadores online. Un linter YAML no valida toda la semántica de Home Assistant.

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

Referencia técnica: configuración actual del sensor MQTT. El ejemplo requiere conexión MQTT, el mensaje indicado y entidades reales; no dupliques claves de nivel superior.