It would be possible without changing the lib. But we’d need a class wrapper around it with logic to handle where the comment was placed. It would be quite a bit of work and testing and it would likely only work in UI yaml mode.
This was a frustrating thread to read. Lots of theories on the technical challenges from user that I’m not sure actually know, and a lot of “well just use X work around” as if that makes the current state of things okay.
Generally speaking, the goal of HA is (and should be) to make it easier for people without technical knowledge to do things, not harder. The need for a way to comment in automations necessarily must start with the UI. At an absolute minimum, the “Rename” option fails to do what’s needed on two fronts:
- It is not desirable to have to erase the existing (automatically generated) description of something just to add your own additional comments.
- Nothing about this option implies that this is the “correct” way to describe something in an automation. If it was, it should be called “Edit Description” not “Rename”
The user experience with this is simply bad. Even if this was the intended way to do things, it is far from intuitive and leaves a lot to be desired.
Furthermore, while the description field exists for some things, it doesn’t exist for all. So even if I want to edit in YAML and add it, I can’t, I get an error. While there are technical reasons that adding comments with # in the YAML won’t really work right, there is no real reason that description or comments could not be fields available on any object. And there is no real reason this text could not be displayed and edited in the UI.
Even where description exists, it doesn’t seem like I can edit it with the UI. For instance, I can describe the automation itself which is good, and the text does display on the UI, but if there is a button to edit it I can’t find it - which indicates it’s either missing, or not located someplace that the average user will stumble upon it.
I came to this thread today because I was looking at a relatively simple automation I made a few months ago and was trying to figure out what on Earth it was doing. Once I figured it out, it made complete sense, but up until that it seemed utterly nonsensical despite the fact that I created it. The need for comments was immediately obvious, but I couldn’t find anything in the UI that would allow for this. To Google I went, and found someone mentioning description so I tried adding it in the YAML… only to get an unhelpful meaningless error.
We need a way to document our own automations. How it works technically is not all that important to the end user, but I can say with certainty that it isn’t that complicated to achieve, and any complication is well worth it.
4 Likes
I would like to request support for preserving # comments in scripts and automations when editing them via the UI using “Edit in YAML”.
Currently, any comments added in the YAML editor are removed when the automation or script is later opened and saved through the UI. This makes it difficult to document logic and structure directly within the configuration.
Motivation / Use Case
Over time, I have built a substantial collection of automations and scripts, some of which have been in use for several years. As automations mature, it becomes increasingly difficult to recall the exact intent, structure, and design decisions behind them. When maintenance or troubleshooting is required, inline comments are critical for quickly understanding how the automation is structured and why certain choices were made.
Additionally, preserving comments significantly improves readability and maintainability when automations or scripts are reviewed, reused, or modified by others.
Expected Behavior
- YAML comments (
#) added via “Edit in YAML” should be retained. - Comments should not be stripped when the automation or script is opened and saved again through the UI.
Preserving comments would greatly improve long-term maintainability and collaboration without affecting existing functionality.
Thank you for considering this request.
1 Like
26k views ! what are we doing here! this needs to be fixed. I have comments in my esphome configs but not automations ? that’s just just silly.
People need to remember that the development team doesn’t spend hours reading the forums looking for new feature requests, which is why this section has been closed to new additions. They spend much more time on GitHub in the repository, which is where people should be showing their support for things like this.
You kinda prove the point of the whole thread ! lol . " homeassistant is not built just for coders and github nerds. " its supposed to bring automation to the initiated masses. not having comments in automation yaml betrays that , having to go to a 3rd party for feed back betrays that. I have had a paid nabucase account for over 5 years. telling the users there plea’s go unanswered on HAs own forums , because you have to use github is a bad look .
Feature requests were moved to github about a year ago. We asked people to recreate feature requests there. Has this been recreated over there yet?
Is that even possible?
docker-desktop:/config# cat foo.yaml
# This is a comment
some_key:
nested_key: value
other_key: value
# And more comments here
other_config: boo
docker-desktop:/config# cat foo.yaml | python3 -c 'import yaml; import sys; print(yaml.safe_dump(yaml.safe_load(sys.stdin.read())))'
other_config: boo
some_key:
nested_key: value
other_key: value
For more compolex automations I tend to use HA packages where there’s no UI to edit them so comments are preserved.
Or in automations in the UI I use the description, aliases, and sometimes even fake variables.
Don’t use the UI.
This is in my configuration.yaml:
automation: !include gui/automations.yaml # this is only for GUI-Automations, do not touch this file!
automation manual: !include_dir_merge_list manual_automations/
Now, all of my automations are in the manual_automations folder. Comments and whitespace is preserved. As a bonus I can organize my 200+ automations in functional folders, like “lights.yaml” to contain all of the automations for my lights.
This works for scenes and scripts as well.