Home Assistant YAML Comments: The Definitive 2026 Guide

Last updated on February 8, 2026

Welcome to the 2026 edition of Chapter 2.1 in our Complete YAML Course. In this definitive guide, we’re diving deep into a fundamental yet often-overlooked feature: Home Assistant YAML comments. We’ll go beyond basic syntax and explore the best practices that will transform your configuration files, dramatically improving YAML readability and making Home Assistant collaboration a breeze—a cornerstone of any serious smart home project.

If you’re just joining us, you can check out the main course page or the full syllabus for our second chapter on advanced YAML.

What Exactly Are YAML Comments?

At their core, YAML comments are lines of text that the system’s parser completely ignores. They have zero effect on the functionality of your Home Assistant configuration. Their sole purpose is to serve as notes for the humans reading the code. In a smart home YAML setup, which can easily balloon to hundreds or thousands of lines, these comments become an indispensable tool for remembering the purpose of an automation, explaining a specific design choice, or guiding other users (or, more often, your future self!).

YAML Comment Syntax: The Hashtag (#) Rule

The YAML syntax for creating a comment is incredibly simple: anything following a hash symbol (#) until the end of that same line is treated as a comment.

You can have comments that take up an entire line or “inline” comments placed after a line of code. Let’s look at some YAML comment examples applied to a 2026 Home Assistant config file:

# --- MQTT SENSORS SECTION --- 
# This section groups all sensors that receive data via the MQTT broker.
# For more info on broker setup, see the Mosquitto guide.
sensor:
  - platform: mqtt
    name: "Living Room Temperature"
    state_topic: "tele/sonoff_th16/SENSOR"
    value_template: "{{ value_json.AM2301.Temperature }}" # Extracts the temperature value from the JSON payload
    unit_of_measurement: "°C"
    device_class: temperature

# --- CLIMATE CONTROL AUTOMATIONS SECTION ---
automation:
  - alias: "Turn on heat when temperature drops"
    trigger:
      platform: numeric_state
      entity_id: sensor.living_room_temperature
      below: 20 # Critical threshold. Decided on 20°C (68°F) after comfort analysis during winter 2025.
    action:
      - service: climate.set_hvac_mode
        target:
          entity_id: climate.living_room_thermostat
        data:
          hvac_mode: "heat"

As you can see, comments provide valuable context that the code itself can’t convey, like the reasoning behind choosing a specific temperature threshold.

Best Practices for Commenting in Home Assistant (2026)

Writing good comments is an art. A great comment can save hours of debugging, while a bad one can create more confusion than it solves. Here are my top best practices, refined over years of managing complex setups:

Comment the ‘Why,’ Not the ‘What’: The code already tells you what it’s doing. A good comment explains why. For instance, instead of # This is a temperature sensor (which is obvious), a better comment is # High-precision sensor used to control the main thermostat.

Structure Your Large Files: In files like configuration.yaml or in packages, use dividers to create visual sections. This massively improves navigation.

#=================================================
# LIGHTING SECTION
#=================================================
light:
  # ...

#=================================================
# SECURITY SECTION
#=================================================
alarm_control_panel:
  # ...

Document Your ‘Magic Numbers’: If you use a number or string that isn’t immediately obvious (like a port, threshold, or token), explain it. The example above with below: 20 is perfect—the justification for that value is crucial.
Keep Comments Up-to-Date: An outdated comment is a landmine waiting to go off. It’s worse than no comment at all. If you change the logic in an automation, make sure you update the comment that describes it.

Add Metadata for Collaboration: In shared or complex configurations, it’s helpful to add info about the author or the last change date, especially for tricky automations.

# Author: John D.
# Last modified: 2026-02-08
# Reason: Adjusted delay to prevent false positives from the motion sensor.
- alias: "Turn off hallway light after 5 minutes"
  # ...

Essential Tools for Working with YAML Comments

In 2026, editing YAML blindly in a basic text editor is no longer an efficient option. To maximize your productivity and ensure the quality of your code and comments, I strongly recommend these tools:

Code Editors with Advanced Support

The de facto standard is Visual Studio Code. With the official Home Assistant extension, you not only get autocompletion and entity validation, but your comment syntax is colored differently, making comments incredibly easy to spot and read. If you’re not using it yet, I highly recommend checking out the official extension on the VS Code Marketplace.

YAML Linters and Validators

A “linter” is a tool that analyzes your code for syntactical and stylistic errors. Tools like yamllint can be configured to, for example, enforce a maximum line length for comments, improving readability. Most of these features are already built into the Home Assistant VS Code extension, which will validate your file every time you save.

Automatic Documentation Generation

For the power users or those managing configurations for clients, it’s possible to use special comment formats (similar to Javadoc or Python’s DocStrings) to generate external documentation automatically. While this is overkill for a typical home user, it demonstrates the power of well-structured comments as a single source of truth for system documentation.

Conclusion: Comments Are the Bedrock of a Maintainable Home Assistant

We’ve seen that Home Assistant YAML comments are much more than simple notes. They are a strategic tool for ensuring readability, simplifying maintenance, and supercharging collaboration. Adopting good commenting habits from day one will save you countless hours down the road and turn your configuration into a robust, manageable project, no matter how complex it becomes.

Now that you’ve mastered the art of documenting your code, you’re ready to continue your journey in our YAML course.

Mastering YAML Comments in Home Assistant: The Ultimate 2026 Guide to Clean Configs