Could there not be a “comment” item available in the automation editor, which takes a string and does precisely nothing with it?
That way, it would be visible in the YAML as well (and in the JSON, should anyone look at that). Not as easy as adding a YAML comment, for those that edit YAML directly, but maybe HA could convert them on save…
Anything that is supported in the YAML can be shown pretty trivially in the UI. So the answer is yes, given petro’s option is implemented first.
EDIT: I misunderstood the question. Petro’s suggestion is comments as a field for any JSON object, whereas yours is to have a JSON object that is just for comments. This could be useful as well.
This field already exists, called alias
I don’t think unikitty is referring to an alias field within an action, but rather an action that only contains an alias. Essentially a dummy action. There would be no dropdown arrow. Just text. Like this:
I currently mimic this functionality by putting a call to script.turn_on with no entities. I then change its alias and disable it. Essentially it becomes a comment
Or just set a delay of 0.1s (or less) if your automation is not super time critical. That way you won’t have to remember to disable it, and any potential future changes to HA will not throw an error 
Even if we added the yaml keyword / GUI field “comment” and had the limitation that there can only be one - it would still be better than nothing.
This field in the GUI should be a multiline field which is put as multiline in the yaml incl the line breaks. It would be a great help being able to put 2-4 lines of text with thing to remember related to a script or an automation.
The alias fields today are OK for one liner few word comments. I just find them confusing because they used to also mean something more specific as I remember it. I understand it is not possible to preserve random comments and out them back the same place again
I think there’s a version of JSON that does comments. Although I’m not sure why we are translating back and forth between YAML and JSON instead of just picking one and sticking with it.
