Skip to content
Home Assistant

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

08/02/2026

Technical review: 27 October 2026. This is a supplementary guide from the previous course, not a numbered chapter of the new course. Follow the current Home Assistant YAML course for the learning sequence.

This supplementary guide explains YAML comments in Home Assistant: how to document decisions, improve readability and keep useful notes without confusing comments with data or Jinja expressions.

For the current learning sequence, visit the Home Assistant YAML course. This page is not Chapter 2.1 of that new course.

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

A comment begins with # outside a quoted string and outside scalar content; an inline comment must be separated from the preceding value. A hash within quotes, or within the content of a block scalar, is data, not a YAML 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:

# configuration.yaml excerpt: adapt existing keys and real entities
mqtt:
  sensor:
    - name: "Living Room Temperature"
      state_topic: "tele/sonoff_th16/SENSOR"
      value_template: "{{ value_json.AM2301.Temperature }}" # Extract temperature from the device payload
      unit_of_measurement: "°C"
      device_class: temperature

automation:
  - alias: "Request heating below the comfort threshold"
    triggers:
      - trigger: numeric_state
        entity_id: sensor.living_room_temperature
        below: 20 # Example comfort threshold; adapt to your home
    actions:
      - action: 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.

Hashes, multiline notes and Jinja comments

# Two lines of comments need two hashes
# There is no /* ... */ YAML comment syntax
color: "#FF5733"
mensaje: |
  # This line is message content, not a YAML comment

This is a generic YAML illustration, not a complete Home Assistant configuration. In a Jinja template, use {# a Jinja comment #}. A hash inside a YAML block scalar will not disable an action or hide text from the resulting message.

Disabling a block without leaving an invalid structure

Comment every relevant line, not just the heading or first key. Leaving children behind can change the structure or produce a validation error. For a temporary automation test, consider disabling the automation through its own controls rather than commenting arbitrary portions of managed files. Check indentation and validate after the change.

Comments, annotations and privacy

A note for a human is a comment. A platform-specific annotation, such as Kubernetes metadata, is actual data and must not be replaced with a comment. Never place passwords or tokens in comments: they are still present in the shared file. Use local tools or sanitized examples rather than uploading private configuration to online validators. A YAML linter does not validate Home Assistant semantics.

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.

Follow Me on YouTube

Subscribe on YouTube - Home Assistant YAML Comments 2026

Technical reference: current MQTT sensor configuration. The example requires an MQTT connection, the stated payload and real entities; do not duplicate top-level keys.