> Comments in JSON? Why isn’t this everywhere?

Comments were considered an anti-feature by Douglas Crockford, the creator of JSON:

> 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.

> Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.

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

* https://en.wikipedia.org/wiki/Douglas_Crockford

I always hated this logic, the "I know better than you". You can still add pragmas trivially in JSON, this doesn't prevent that problem, it just makes it more convoluted at the expense of a powerful documentation feature.

This really never made sense; I find adding property like __pragma: nicer than comments. It has the same problem as he stated, but leaving out comments is not going to prevent that; it was a bad idea IMHO. I use hjson just for the comments; it's excellent.

> This really never made sense

It always made perfect sense, given JSON was invented as a data exchange format. It was never intended to be written out by hand.

> I find adding property like __pragma: nicer than comments. It has the same problem as he stated

It does not, because that is data which every JSON parser will at least parse if not interpret.

A comment is something a parser has no reason to yield, which means smuggling metadata in comments makes the document itself inconsistent between parsers which do and parsers which don't[0] expose comments.

And this was not a fancy Crockford made up, smuggling processing instructions in comments was ubiquitous in Java at the time, as well as HTML/XML, where it literally still is a thing: https://en.wikipedia.org/wiki/Conditional_comment.

[0] and possibly can't, how do you deserialize a comment in the middle of an object to JS or Ruby

> I always hated this logic, the "I know better than you".

Feel free to create your own data interchange file format. (Perhaps with Blackjack and hookers. :)

> You can still add pragmas trivially in JSON, this doesn't prevent that problem, it just makes it more convoluted at the expense of a powerful documentation feature.

Computers/systems do not need comments to exchange data between themselves, and that is the problem JSON is trying to solve: data exchange.

If you're using it for configuration and other human-centric tasks, and wish to communicate human-centric things in the file, you're trying to fit a square peg into a round hole. Use some other format that was designed with those things in mind.

If you're saying the designers of a hammer didn't think of being able to handle Robertson screws you're unfairly critiquing the tool.

> Feel free to create your own data interchange file format.

This is such a lazy argument to make. We are both allowed to criticize flaws in data exchange formats. As far as what JSON is trying to solve, it's far beyond that, and the creator knew this (which is why he went out of his way to fight it). If you as a human have ever debugged anything dealing with a json API, you've already proven that comments can have value.

And still JSON is less of a pain than XML... ;-)

It's a square peg that fits very nicely in the round hole I use it for, so Imma continue to use it as I see fit.

The original reason is that they didn’t want people to use comments for processing information.

Because preserving them across processors (think jq) is hard or impossible.

It's a shame because it's a rather trivial thing to filter out. Personally I wish they would have left out the "//" single-line commenting to avoid the whitespace dependency.

Filtering them out is indeed trivial, but then they're not stable / preserved, and so why bother writing them?

Ensuring that comments and their locations in the text are preserved by processors is quite difficult if not impossible. Reformatting a JSON text alone can "break" comments by not necessarily placing them where they belong. Any schema transformation means comments must be dropped.

You can write a parser that generates an AST node for comments and then pretty prints that AST. So it’s not impossible, but it does require that your parser gives you the option to not just drop comments on the floor.

Alright, here's a JSON5 text:

  {
    // start
    x: "y",
    // the following is foo
    foo: "hey",
      // the following is bar
    bar: "there"
    // end
  }

When parsing it, should I attach each comment to the following name or the previous name?

If I reformat to change indentation, should I change the indentation of the comments too? How would the comment that reads "the following is bar" be re-indented?

What if there are duplicate names? JSON does allow duplicates. If I attach comments to preceding (or following) names, then while parsing I find a dup... what should I do with the preceding comment and the new name?

You make the comment a child node of the object literal node, don’t associate it with the following key/value pair at all. When you pretty print it, it will have the same relative order with the following kv pair as it had originally (and you cannot reorder json keys safely because the handling of duplicate keys is implementation-defined).

As far as indentation goes, if I were writing a pretty printer, I’d make indentation handled by the object/array node not by the comment/kv pair node. So that doesn’t matter: the comment will start printing at whatever the current column is just like the kv pairs would.

Anyways, among other tools, prettier has already solved this problem.

> You make the comment a child node of the object literal node, don’t associate it with the following key/value pair at all. When you pretty print it, it will have the same relative order with the following kv pair as it had originally (and you cannot reorder json keys safely because the handling of duplicate keys is implementation-defined).

Many implementations parse objects into hash tables and lose duplicates and even order of appearance of name/value pairs, and all of that is allowed. Such implementations will not be able to keep relative order of comments.

Don’t use that sort of implementation for a pretty printer is my point. I’m not saying you can pretty print json that has been parsed by a generic parser, but that you can write a parser that can pretty print arbitrary json.

But pretty-printing is not all that one does with JSON. If that were all one ever did with JSON then JSON wouldn't exist.