It seems HA is removing all comments expressed as # in front-end cards.
I find it super useful to document why I do things a certain way (especially since I cannot always design things without duplication due to gaps in my own knowledge or limitations of the platform) so documentation is super important to be able to maintain my code.
Any ideas how to stop HA from removing my comments?
NB: in addition to the post marked as Solution, also see this post further down for extra info
You can’t. That’s just the way the system works.
this has been a big request over the years. But TBH I’m not sure there isn’t some technical limitation that prevents it.
At least you can’t if you use the UI mode of configuration of the frontend (storage mode). If you use yaml mode and configure things manually then you can put comments in anywhere you want.
The YAML gets converted to JSON. JSON does not have comments.
Yep, can’t use comments in JSON files.
EDIT: Andrew beat me to it
Only if you use storage mode and edit it using yaml.
if you use yaml mode then that doesn’t happen and you can use comments any time you want.
This sounds like, for lack of a better description, a shortsighted decision on the part of the UI editor. There is no reason to discard the source code, the yaml that the UI generates, when it’s converted to JSON. Do you delete your C code when it’s compiled into a binary file? No. Do your comments survive the compiler into the binary? No. So, why isn’t the source YAML file saved including comments when it is converted to JASON?
From ChatGPT:
JSON does not support comments because its creator, Douglas Crockford, deliberately removed them from the format to prevent misuse and keep it as a pure data-only format. Crockford observed that some people were using comments to store parsing directives, which could break compatibility between different systems. Therefore, JSON only allows key-value pairs, meaning that every line should be a piece of data, rather than a function or a variable like in typical programming languages. However, there are still ways to make comments in JSON. For example, you can use a leading _ to indicate that the following line of data should be ignored by the parser running it. Alternatively, you could use the conventional JavaScript // instead
From the point of view of a user implementing this a a no-brainer, but not from the point of the developer of the parsing library. I say this from my experience working with xml parsing libraries, like the default in Python, that eliminates comments too. The hurdle is to make the library aware of comments, which means creating new procedures to store their content, position and even indentation. Yes, perfectly doable but requires some work and tons of testing.
This part makes me wonder also… so, correct me if i’m wrong:
Isn’t that “kinda” stupid? Deleting source file, recreating it, deleting it again, recreating it again…? Yeah, i’m not a programmer, so i guess i’m thinking it wrong… or am i?
The underlying conversion between JSON and YAML is irrelevant to the retention of comments. There’s no technical reason that comments cannot be treated as just another field in the JSON. That’s entirely a design choice on the part of the developers (which I would assume was made to simplify the schema).
Yeah, no… comments can’t be stored in a separate field in json as the structure would change its shape.
e.g.
type: entities
# this should be important
entities:
###############
# my entities #
###############
# This is sensor x
- name: X
# the id does this
entity_id: sensor.x
# Something else is important
# But this is very important, so lets make this important.
- name: Y
entity_id: sensor.y
converts to
{
"type": "entities",
"entities": [
{
"name": "X",
"entity_id": "sensor.x"
},
{
"name": "Y",
"entity_id": "sensor.y"
}
]
}
Here’s a test, seeing that you say there’s no technical limitation. Add the comments from the yaml into the json. Make sure the json retains it’s meaning and the comments hold their position in the yaml.
{
"type": "entities",
"entities": [
{
"name": "X",
"entity_id": "sensor.x"
},
{
"name": "Y",
"entity_id": "sensor.y"
}
],
"__original__": "type: entities\n# this should be important\nentities:\n###############\n# my entities #\n###############\n\n# This is sensor x\n- name: X\n # the id does this\n entity_id: sensor.x\n# Something else is important\n\n# But this is very important, so lets make this important.\n- name: Y\n entity_id: sensor.y"
}
Just store the original user input in a field and voila → nothing gets lost.
That doesn’t work when in UI mode, the fields will update but the original will remain the same. There’s a lot more that goes into this other than a simple “This will work” by people who haven’t even bothered learning how the system works and what libraries it uses (in python, js, and ts).
Add a warning when a user clicks UI mode: If you switch to UI mode, your comments and original formatting will be removed! Are you sure you want to continue? <yes> <yes, don't show the warning again> <no>.
I’m responding to the claimed “impossibility” to store comments in in JSON. But you’re right → I’d expect that trivial thing would have already been implemented, so there are probably multiple obstacles.
I wouldn’t say I “didn’t bother”. I wish I could help. I’m just still too noobish to contribute more than simple docs improvement PRs. For now, I hope… Cheers!
{
"type": "entities",
"_comment_entities_pre": "this should be important",
"_comment_entities_post": "###############\n# my entities #\n###############\n\nThis is sensor x",
"entities": [
{
"name": "X",
"entity_id": "sensor.x",
"_comment_entity_id_pre" : "the id does this",
"_comment_entity_id_post" : "Something else is important",
},
{
"_comment_name_pre" : "But this is very important, so lets make this important.",
"name": "Y",
"entity_id": "sensor.y"
}
]
}
Meta tags with a modified YAML parser / writer (and no, it will not be able to entirely keep the weird illogical comment indentation in your example, but it can be adapted to even support that). This isn’t rocket science. This is a solved problem. It’s not about this to be impossible (of course it’s not), it’s about the dev team not wanting to spend the time implementing it. Whether it would actually make sense to implement something like that is debatable of course, but so is this whole strange YAML->JSON->YAML stuff.
Oh and JSON5 is another option (JSON with support for comments).
I purposely made it have gotchas in it, and you took the bait. Your meta sequencing won’t work and the first comment won’t be placed in the correct spot.. Edit: just read up on meta tags for json, didn’t know these existed. It’s a good idea, it would need to be natively supported by the json loader HA uses.
Yes, it is possible to do this, but there’s more development than just “add this”.
By all means, why don’t you spear head this and add it in? No one on the dev team against this change and it’s mostly frontend anyways (Can’t use the “python is bad” excuse again)
Edit: just needs to work with the built in python js lib. So if you’re serious about wanting this, that’s a requirement.
thanks very much @petro and thanks all for your contributions to the discussions.
i’m relatively new to HA so i’m learning a lot even just from reading the discussion.
i’m marking petro’s last comment as the solution as that seems to be the answer to my question.
let me know if you disagree and i can unmark.
Hm…just out of curiosity: who would be changing UI except me? HA system? How?
You’d edit the card via the ui, which would cause the json to get out of sync with the raw yaml containing comments.
Well…. I meant: when i edit card in UI and i hit “save” whole thing is converted to json (so far so good). BUT… why wouldn’t be possible to keep that yaml with all comments and when compiling just left out comments ? So when i re-open my yaml comments would be still there.
The whole thing is stored in JSON, there’s no conversion. There’s a conversion to yaml when you switch to yaml mode.
HeyImAlexs meta tag idea is the only way to solve this as the built in json lib for python & js do not support json5. So all we’d need is someone to take the lead and add a PR.