Item — HN Reader

To me the biggest annoyance of json is there's no standard way to put comments in there. What's the point of a text-based serialization format if it can't carry comments???

It has one advantage over YAML though, with JSON you know when you're not at the end of the file :-)

2 comments

The downside of this is that the comment becomes just another piece of the data model, because anything that consumes that JSON will need to decide: do I preserve comments, or remove them, when re-emitting the JSON?

If I remove them, comments are kind of only useful for things like initial config files or what have you. Which might be fine for your use case, but JSON broadly is not about making configuration files - this is more suited for something like YAML.

If you preserve them - how is that different from a key-value just named "comment": "Here's my comment"? (And if the answer is "because it might not crash poorly coded applications," that's more of a discussion about the application than it is about comments in JSON)

Consider the comment as like a header in HTTP in relation to body content: a side channel for information. I despair that anyone was putting processing pragmas in comments, but you can’t beat all the human out of a programmer.

The word “Notation” in JSON and the fact that JSON allows an arbitrary quantity of ignored bytes in any object (whitespace) imply that comments would have been just fine. How many JSON processors are required to preserve whitespace? (Ignorant here, I’ll take any informed answer and learn from it.)

Often times people add comments in-line with things to prevent the comment from becoming stale should the referent change (because the inlining encourages modifying the comment if the referent is modified), whereas it may be hard to determine the referent of a comment in its own field.

Further, having multiple comments with the same field name is invalid JSON I believe, as keys must be unique? Though I may be wrong. (however, if keys _must_ be unique, then comment authors could encode the referent in the comment key, possibly).

>If I remove them, comments are kind of only useful for things like initial config files or what have you.*

True, but that's a pretty big use case to dismiss with "only". I don't think people want their json api responses to be able to include comments, but it's definitely convenient to be able to comment out parts of a config file. How/if to expose that through the deserializer is an interesting question, it would be fine with me if it dropped them.

Comments were an anti-feature of JSON: purposefully removed. JSON was (originally) meant as a machine-to-machine interchange format, and why would machines need comments? From the creator of JSON, Douglas Crockford:

> I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn't.

* https://web.archive.org/web/20120507093915/https://plus.goog...

Basically: he didn't want people to start putting in pragmas in comments.

2012 discussion:

* https://news.ycombinator.com/item?id=3912149