I would like to have comment field to in both automations and scripts.
Comments with # can’t be used in UI.
Dedicated field for this would be best solution.
We can call it comment or description, and in UI editor it should be displayed at the begining of the automation / script.
1 Like
It’s not pretty, but I’ve solved this by creating a “helper” text input text field called “comments”.
When I want to have a comment, I just call the service input_text.set_value and put whatever I want my comment to be.
2 Likes
GF, I have been struggling with this for a while! Some people believe REM statements are a sign of bad programming. (Young people say, "Comments are for bad ‘coders’ but I like to comment my code. When I put comments directly into the yaml code, they work, but the next time I use the UI for any code, all my comments are removed. Could you please explain how you ‘call the service’ to put comments into automations.yaml?
TIA
I couldn’t agree more. I’m almost embarrassed to admit how many times I’ve spent several days hammering out an automation, only to come back some time later to make a change and not being able to figure out what I was thinking when setting it up. Adding a comment here and there to remind my future self what I was thinking would go a long way. In my mind, I imagine it being much like the (relatively) new trigger IDs. To add one, you click the trigger menu drop down and select “Edit trigger ID”, except these would be with actions instead of triggers, and instead of adding trigger IDs you’d be adding comments.
3 Likes
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.
1 Like
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
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.
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!
I typically just rename blocks to be more descriptive. That way future me knows what current me is actually thinking. It’s not as good as a comment block, but it works for now.
1 Like
I put it all in the description block for paragraphs, otherwise you can add # or {# #} comments everywhere as long as you don’t save it in the ui editor, that strips all the things including spaces for efficiency in the storage when it parses the code to make sure it works then saves it in automaton.yaml
1 Like
I generally use the UI editor to create the automation, then move it to a my_automations.yaml file to tweak it and add comments. If future me really needs to use the UI for some reason, he can always copy and paste the code back to automations.yaml or right into the UI. Hasn’t happened yet.
I do, but it’s not maintainable having a long name like “nodered flow X uses this value with event K that’s misaligned of N minutes”.
on next UI saving (that can happen, it’s easier changing via UI instead of doing SSH login to server and manually change automation), all the comments will be stripped out, so it’s a bit risky
Thanks, I guess I didn’t explain that well enough.
I have a second !include statement in my configuration.yaml which points to my_automations.yaml:
automation ui: !include automations.yaml
automation manual: !include my_automations.yaml
My “production” automations are in this second file, which HA can’t edit. It still loads and runs all the automations, but it can’t re-format them, erasing all the comments. No need to SSH in to edit, I use SMB.
I only use the UI to create new automations using logic I haven’t used before. Otherwise I just copy-and-paste from existing, working automations. Once I’ve got one working the way I like, it gets moved to the my_automations.yaml file. In a pinch, I can always move them back for more development work in the UI.
As I’ve said before, there are other ways to document your automations. This method was what was available when I started with automations, and it works for me. YMMV.
2 Likes