We don’t need none of this tweaks, I discovered that we can write comments/free texts in the description field. In the 3 dots menu when editing an automation, open the 3 dots menu, click “rename”, and it’s possible to edit the automation name and also a long description.
2 Likes
Whenever I add comments in the ‘yaml’ version (to know what I’m doing e.g. when setting up a template) and switch to UI version all the comments are deleted
Similar as Why does dashboard not allow comments in the code
The code is stored as json, and json doesn’t do comments. For automations/scripts it is a bit more complicated, but it is first stored as json, and then converted back to yaml for automations.yaml and scripts.yaml
2 Likes
While there is no way to handle YAML comments for the reason TheFes said, what could be possible is adding more commenting options to the UI. Like a comment type action that does nothing but lets you insert descriptive information somewhere. Or an option to add a description to actions, conditions and triggers which is presented as a text area, as opposed to an alias which is more of a name. This would make more sense in the UI editor anyway since YAML is basically the fallback for advanced features there.
3 Likes
it’s not because the code is stored in json. It’s because it is stored the way which makes it impossible.
it comes from direct conversion from yaml to json. but who said the comment cannot be treaded as any other language object?
I have to admit it ‘must not be easy especially if there is no yaml-json converter which can do that.
but creating language which ‘eats’ comments without warning?
3 Likes
The automation editor has to parse the YAML in order to present it to you in a form-based way like it is. YAML parsers remove comments because they’re comments. By definition they are supposed to be ignored since they aren’t part of the data so why would a YAML parser do anything but ignore them?
Even if you do the “edit in YAML” option at the top its still parsing the YAML and showing you a subset. You’ll notice the if you actually look at the automations.yaml file each automation has an id field and that doesn’t appear in the UI even in the raw YAML view since changing it would break things.
The only way the automation editor could keep comments is if it didn’t parse it at all and kept it purely as text. And if that’s what you want then just don’t use the UI editor. Add a new automation block and edit your automations in the text editor of your choice.
Since the migration process is non-reversible it seems like this would be a good place for a big warning message, explicitly stating in the non-reversible migration all comments will be removed in your existing automations.yaml file.
It was quite a surprise when all my nicely commented and arranged yaml code disappeared.
6 Likes
It would be great if all objects would have a “comment” field where we could put our comments in a string. That way, they could be kept even if they would not have a functional utility.
3 Likes
Both Labels, Tag’s & Folders
I would like it, If an object or entity (script/Automation) had A label/tag option, that excepts “/“ that represent sub tags or Folders in the GUI & “,” as separate Tags. E.g.
- Tag: “Lights” shows in the GUI in the Folder “Lights”.
- Tag: “Light/Effects” would show in the GUI in the Folder “Effects”, nestled under the Folder “Light”.
- Tag: “Lights, Effects” would show in the GUI in both folders “Effects”, & the Folder “Lights”.
- Tag: “Light/Effects, Light” would show in the GUI in both folders “Light”, & the Folder “Effects”, nestled under the Folder “Light”.
- Tag: ““is empty”” or “root” would show up under the root folder in the GUI.
alias: A Light Script
tags: light, light/effects
sequence:
- service: light.turn_on
data: {}
target:
area_id: office
mode: single
And the “Tag” option can be reference via HAss Jinja2 extension’s
state_attr ( script.a_light_script, 'tags')
When moving entities in the GUI to a different folder, the GUI gives the options “Change” &or “Both”.
Reference# Labels, Tags & Folders for Automation Scripts
There is a potential workaround though, since templates can contain comments, and these are not removed by the UI. Add a template condition at the relevant point. Make it always return true so it can’t affect subsequent command execution, then put comments in there, like so: -
condition: template
value_template: |-
{# COMMENT BLOCK FOLLOWS #}
{# this is a comment #}
{# and here is another #}
{# as many as you like #}
{{true}}
5 Likes
I would really like a simple solution to this.
I’m new here but I’ve managed to write some fairly complex automations to control my smart radiator valves.
I would very much like to be able to add comments to the yaml because:
I’m in the UK and we’re coming to the end of winter.
In six months time I expect to come back to these heating automations and I’d really like to have comments to remind me how they work 
Young people [may] say, "Comments are for bad ‘coders’
But young people lack the wisdom to see their value.
I’ve been a programmer for over 50 years (yes, I started out as a “young person”
) and I’ve learned to both treasure and insist on comments/remarks/descriptions in code. Not useless comments that describe what is being done - that should be self-evident from the code. Such comments just add noise. I mean comments that explain reasons and significant context that is not otherwise evident.
There’s a reason that all good development standards require comments (and often in a structured form). That’s because the code shows what is done (or is to be done) but it can’t explain with any clarity why it is done like that. Obviously, in large systems there is a heap of design & architecture documentation, but that is big picture stuff (and often can become detached from the source code when it’s distributed). Down at the detailed code level, the programmer needs to pass on to their successors the reason a particular approach is used and the constraints that that approach addresses (often outside the immediate context of the code in question).
In the context of HA Automations, I find it necessary to document not just the purpose of the automation – that can be done in a description – but also, for example, the reason a particular condition is there or the secondary event that a particular action may trigger.
It is indeed unfortunate that the migration to a “visual” interface in HA has downgraded the YAML to the extent that it has. It was particularly unfortunate that it was decided to “blow away” any comments in the YAML code on migration to the visual form without even so much as a warning (at event time, not in the release notes) that that would take place.
It seems that each generation of technologists has to re-learn the hard-learned lessons from the previous generation.
Brian
4 Likes
Pity that Scripts don’t have an UI for descriptions the same as Automations (thanks, Claudio!)
Nonetheless, the yaml for Scripts accepts the description field and doesn’t remove it.
Likewise:
alias: Random Lights
mode: single
description: >-
See
https://www.example.com/reference
sequence:
3 Likes
For reference, a similar FR which had been active for a while was closed, with a link to this FR as a duplicate. Fair enough, but I wanted to include the link here since that thread had been going for a while and may contain posts some readers here may find interesting.
Most of this and that other FR is implemented, just not in how you’d expect. There’s a description field as rudolff pointed out. Also, all actions, conditions, and triggers allow alias which is used to describe that “step” for the frontend. Variables allow jinja comments ({# ... #}) as well.
3 Likes
Good point, there are workarounds. This FR is still a good idea, but I suspect it would be hard to implement.
My own workaround (post #2 of the other thread) is not to use the UI for automations, except maybe just to try out something new.
Being that the YAML is converted to JSON when saved, then back again to YAML for editing, a compromised would be to store the original YAML file as-is in a text file, before converting it to JSON. When the user comes back to the YAML at a later date for editing, instead of converting the JSON back to YAML, simply retrieve the associated YAML text file and display it to the user. Nothing is going to change the JSON in the meantime, so the stored text file should always be up to date with the JSON. Readability of code is important. Dropping helpful comments which enhance the readability of config files should be avoided if possible.
4 Likes
Or simply adding fake JSON node for comment - something like 'comment':'comment from YAML' …
4 Likes
The problem isn’t adding a comment or a description node to the json, it’s reading the comments in the yaml. Typical YAML parsers will not parse comments, they will just ignore them entirely, because that’s what the YAML specs say they should do:
Comments are a presentation detail and must not have any effect on the serialization tree or representation graph. In particular, comments are not associated with a particular node.
Of course that doesn’t mean a YAML parser couldn’t preserve them as an out-of-spec extension (so to facilitate format conversions or source formatting for example) and some probably do. But I guess the one HA uses doesn’t.
2 Likes
When developing automation that are related, or automation that relies on the execution of other automation or other external things (like nodered), it can be a mess to maintenance all of those things after some time or after feature changes.
A new comment textbox to be inserted in the automation, or a textbox added in existing automation’s blocks, could be useful to describe the why’s to the future yourself, looking at same automation/script in the future, of why you’ve done the things in that way.
A text string of some hundreds of characters I hope could be enough.
ps
I’m an HA user since 0.101 , so I have used also nodered to accomplish my ideas and now I’ve no time to migrate everything to HA.
Thank you!