4 ms·

Inability to write comments has been a big driver to YAML instead.

t-writescode 6y ago
But with that positive comes all the negatives of YAML, especially around arrays of structs vs regular arrays or arrays of structs which contain one key-value pair each, and especially the struggles around multi-line strings or other kinds of entries in YAML. I don’t think it’s worth the cost and would rather pass some extra keys in JSON that my parser ignores (since additive changes should never cause bugs in data contracts), or a regular key ‘comment/description’.
- jhanschoo 6y ago
  > especially around arrays of structs vs regular arrays or arrays of structs which contain one key-value pair each, and especially the struggles around multi-line strings or other kinds of entries in YAML. Can you give examples? I don't see how they pose a problem.
  - t-writescode 6y ago
    To create a multi-line string in YAML, you can prefix a preceding line with: > | >+ >- |+ |- >+# and so on. How do you know which to use and what does what?! Especially when you see other people doing it in their code and you don't know why. I think they could have done it more cleanly by being more verbose. Python's """ syntax or even Ruby's <<EOL EOL format are cleaner.
- hnlmorg 6y ago
  > But with that positive comes all the negatives of YAML, especially around arrays of structs vs regular arrays or arrays of structs which contain one key-value pair each Are you able to elaborate on this problem? I'm not going to defend the complexity of YAML but I've never ran into any issues with storing complex structures within in. > and especially the struggles around multi-line strings or other kinds of entries in YAML. YAML actually has pretty sophisticated handling of white space within strings. The problem isn't that whatever edge case you run into can't be done, the problem is that YAML covers so many edge cases with different parsing operators that it becomes a bit of a cryptic mess trying to remember which operate is needed when. Though in fairness, JSON was never intended to be human readable (it was meant to be machine generated and machine read) so it's not any better in the readable whitespace department. > I don’t think it’s worth the cost and would rather pass some extra keys in JSON that my parser ignores (since additive changes should never cause bugs in data contracts), or a regular key ‘comment/description’. A third option would be to use hash-prefixed comments (like in Bash) then run that JSON through a YAML parser since technically YAML is a superset of JSON (literally, valid JSON is also valid YAML). Though I do accept that would be an unattractive option to some because you end up with less strict format checking of your source JSON (less strict in the JSON sense).
  - t-writescode 6y ago
    > the problem is that YAML covers so many edge cases with different parsing operators that it becomes a bit of a cryptic mess trying to remember which operate is needed when. This was exactly my point around multi-line strings. You look at a mess of >'s and |'s and it's absolutely not intuitive which one you should use if the configuration files for one of the languages you're required to use happens to use YAML. In json, there's virtually no ambiguity. Everything's either a string, a number or a bool or a struct, and they all have exactly the same shape with ... really no options to make things "easier" As for structs and arrays, YAML doesn't really make them clear, in my opinion, due to its lack of opening and closing values. So, if you're new to k8s and need to make a configuration change to something because the darn thing doesn't work, you're forced to learn yet another markup language when it could just be a very familiar and comparatively intuitive json blob. For example, options: - key: value foo: bar thing: thing2 smell: apple "Oh, so to fix this, I just need to add another entry to turn on the debug flag? And it's 'debug: true'? Oh, okay, so that's ... options: - key: value foo: bar thing: thing2 smell: apple debug: true right? Oh, no? It's not... well what is it? And then a long conversation with a coworker later, they explain, "Oh! No no no, it's this:" item: - key: value foo: bar thing: thing2 smell: apple - key: value2 debug: true Turns out debug was another option you needed to add. Or, in other places in some syntax, you see a bunch of: items: - entry - entry2 - entry3 or item: 1 item2: 2 item3: 3 I've familiarized myself more with YAML over time; but, its learning curve is substantially more difficult than: { "everything is inside curly brackets": "keys and values can be strings", "there's a comma at the end of everything: [ "arrays exist", "they're also comma delimited", 1, "types don't matter" ] }
    - hnlmorg 6y ago
      To be honest I much much prefer YAML for manually handling multiline strings. And frankly JSON's strictness on commas after all except the final entry catches me out so many times (it doesn't help that most parsers aren't great at pointing out where the missing comma is). Being pragmatic, I'd say neither serialisation format is better than the other. JSON does something things better (It's easier to grok nested structures and simpler to reason about the specification) but YAML does other things better (easier to embed multiline blocks of text, handles streaming better, supports comments). Let's not also forget that most of the stuff that people dismiss in JSON is only solved by unofficial hacks (eg jsonlines) that might be widely supported but you cannot rely upon universally. So then you have two problems: a standard that doesn't support x and multiple different implementations that don't strictly support the standard. YAML is a hell of a lot better when it comes to removing undefined behaviour in parsers -- even if that does come at a cost to the complexity of the specification.
spicybright 6y ago
So, besides not playing nice with other parsers, I wonder if there's much harm in adding `//` and `/*` style comments. For example, if you use a specific structure of json for a config file in project you make, you could add comment support to your parser. I also wonder how much of a pain it would be to add comments to json, like a json v2
- IshKebab 6y ago
  It exists: https://json5.org/ https://json5.org/ However I think it goes too far. E.g. why support single quoted strings? That just makes parsing harder. I prefer the format Microsoft uses in VSCode and Typescript - JSONC. It's just JSON but with trailing commas and comments. The downside is it isn't obvious when something is JSON and when it is JSONC because they use the same extension.
  - crehn 6y ago
    > why support single quoted strings? That just makes parsing harder. And something that a lot of language designs ignore: it makes writing harder and unnecessarily contentious. People will use them inconsistently, which has the usual effects any inconsistency has on cognitive load: causes others to question why/how/where.
  - olliej 6y ago
    While there are many things that make any change to json changes challenging, single vs. double quote really isn’t a problem, the JSC JSON parser supprots them at an implementation level as it is also used for jsonp insanity, it’s just that in pure JSON mode (eg JSON.parse) it doesn’t allow single quotes or a few other similar “real” js language features it supports for the sake of jsonp
- reificator 6y ago
  Comments in JSON are easy. You just strip them out before sending to a strict parser. Some parsers even support them out of the box. In fact they're so easy they were already in JSON, and then later removed. > I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. ~Douglas Crockford
IvanK_net 6y ago
I write comments in JSON as properties, which I will never use in practice. E.g. { "name":"jack", "age":42, "---comment":"this is a person" }
deleted 6y ago
[deleted]
crehn 6y ago
But unfortunately YAML is a complex maximalist mess with a million ways to do the same thing and more ways to shoot yourself in the foot.

But with that positive comes all the negatives of YAML, especially around arrays of structs vs regular arrays or arrays of structs which contain one key-value pair each, and especially the struggles around multi-line strings or other kinds of entries in YAML. I don’t think it’s worth the cost and would rather pass some extra keys in JSON that my parser ignores (since additive changes should never cause bugs in data contracts), or a regular key ‘comment/description’.

jhanschoo 6y ago
> especially around arrays of structs vs regular arrays or arrays of structs which contain one key-value pair each, and especially the struggles around multi-line strings or other kinds of entries in YAML. Can you give examples? I don't see how they pose a problem.
- t-writescode 6y ago
  To create a multi-line string in YAML, you can prefix a preceding line with: > | >+ >- |+ |- >+# and so on. How do you know which to use and what does what?! Especially when you see other people doing it in their code and you don't know why. I think they could have done it more cleanly by being more verbose. Python's """ syntax or even Ruby's <<EOL EOL format are cleaner.
hnlmorg 6y ago
> But with that positive comes all the negatives of YAML, especially around arrays of structs vs regular arrays or arrays of structs which contain one key-value pair each Are you able to elaborate on this problem? I'm not going to defend the complexity of YAML but I've never ran into any issues with storing complex structures within in. > and especially the struggles around multi-line strings or other kinds of entries in YAML. YAML actually has pretty sophisticated handling of white space within strings. The problem isn't that whatever edge case you run into can't be done, the problem is that YAML covers so many edge cases with different parsing operators that it becomes a bit of a cryptic mess trying to remember which operate is needed when. Though in fairness, JSON was never intended to be human readable (it was meant to be machine generated and machine read) so it's not any better in the readable whitespace department. > I don’t think it’s worth the cost and would rather pass some extra keys in JSON that my parser ignores (since additive changes should never cause bugs in data contracts), or a regular key ‘comment/description’. A third option would be to use hash-prefixed comments (like in Bash) then run that JSON through a YAML parser since technically YAML is a superset of JSON (literally, valid JSON is also valid YAML). Though I do accept that would be an unattractive option to some because you end up with less strict format checking of your source JSON (less strict in the JSON sense).
- t-writescode 6y ago
  > the problem is that YAML covers so many edge cases with different parsing operators that it becomes a bit of a cryptic mess trying to remember which operate is needed when. This was exactly my point around multi-line strings. You look at a mess of >'s and |'s and it's absolutely not intuitive which one you should use if the configuration files for one of the languages you're required to use happens to use YAML. In json, there's virtually no ambiguity. Everything's either a string, a number or a bool or a struct, and they all have exactly the same shape with ... really no options to make things "easier" As for structs and arrays, YAML doesn't really make them clear, in my opinion, due to its lack of opening and closing values. So, if you're new to k8s and need to make a configuration change to something because the darn thing doesn't work, you're forced to learn yet another markup language when it could just be a very familiar and comparatively intuitive json blob. For example, options: - key: value foo: bar thing: thing2 smell: apple "Oh, so to fix this, I just need to add another entry to turn on the debug flag? And it's 'debug: true'? Oh, okay, so that's ... options: - key: value foo: bar thing: thing2 smell: apple debug: true right? Oh, no? It's not... well what is it? And then a long conversation with a coworker later, they explain, "Oh! No no no, it's this:" item: - key: value foo: bar thing: thing2 smell: apple - key: value2 debug: true Turns out debug was another option you needed to add. Or, in other places in some syntax, you see a bunch of: items: - entry - entry2 - entry3 or item: 1 item2: 2 item3: 3 I've familiarized myself more with YAML over time; but, its learning curve is substantially more difficult than: { "everything is inside curly brackets": "keys and values can be strings", "there's a comma at the end of everything: [ "arrays exist", "they're also comma delimited", 1, "types don't matter" ] }
  - hnlmorg 6y ago
    To be honest I much much prefer YAML for manually handling multiline strings. And frankly JSON's strictness on commas after all except the final entry catches me out so many times (it doesn't help that most parsers aren't great at pointing out where the missing comma is). Being pragmatic, I'd say neither serialisation format is better than the other. JSON does something things better (It's easier to grok nested structures and simpler to reason about the specification) but YAML does other things better (easier to embed multiline blocks of text, handles streaming better, supports comments). Let's not also forget that most of the stuff that people dismiss in JSON is only solved by unofficial hacks (eg jsonlines) that might be widely supported but you cannot rely upon universally. So then you have two problems: a standard that doesn't support x and multiple different implementations that don't strictly support the standard. YAML is a hell of a lot better when it comes to removing undefined behaviour in parsers -- even if that does come at a cost to the complexity of the specification.

spicybright 6y ago

So, besides not playing nice with other parsers, I wonder if there's much harm in adding `//` and `/*` style comments. For example, if you use a specific structure of json for a config file in project you make, you could add comment support to your parser. I also wonder how much of a pain it would be to add comments to json, like a json v2

IshKebab 6y ago
It exists: https://json5.org/ https://json5.org/ However I think it goes too far. E.g. why support single quoted strings? That just makes parsing harder. I prefer the format Microsoft uses in VSCode and Typescript - JSONC. It's just JSON but with trailing commas and comments. The downside is it isn't obvious when something is JSON and when it is JSONC because they use the same extension.
- crehn 6y ago
  > why support single quoted strings? That just makes parsing harder. And something that a lot of language designs ignore: it makes writing harder and unnecessarily contentious. People will use them inconsistently, which has the usual effects any inconsistency has on cognitive load: causes others to question why/how/where.
- olliej 6y ago
  While there are many things that make any change to json changes challenging, single vs. double quote really isn’t a problem, the JSC JSON parser supprots them at an implementation level as it is also used for jsonp insanity, it’s just that in pure JSON mode (eg JSON.parse) it doesn’t allow single quotes or a few other similar “real” js language features it supports for the sake of jsonp
reificator 6y ago
Comments in JSON are easy. You just strip them out before sending to a strict parser. Some parsers even support them out of the box. In fact they're so easy they were already in JSON, and then later removed. > I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. ~Douglas Crockford

IvanK_net 6y ago

I write comments in JSON as properties, which I will never use in practice. E.g. { "name":"jack", "age":42, "---comment":"this is a person" }

deleted 6y ago

[deleted]

crehn 6y ago

But unfortunately YAML is a complex maximalist mess with a million ways to do the same thing and more ways to shoot yourself in the foot.