JSON's Biggest Problem
If there is one single problem I would identify with the now nearly ubiquitous JSON format, it's the absence of comments.
Why is this a big deal?
- Comments can be used to document. Since JSON has gained currency as a configuration file format, this is a big deal. Take a look at the default Apache configuration file. Take a look at
/etc/hosts. Comments play an important role as unstructured inline documentation. - Sometimes things need to temporarily go away. Sometimes during testing, it can be necessary to change large sections of a data file. Being able to toggle a couple of comment sections is the easiest way of doing this. But as JSON stands now, this sort of thing requires keeping multiple copies of a file around (and synchronized).
I'm hardly the first person to criticize JSON for this, and Douglas Crockford, the author of the JSON spec, has responded to this criticism. But his response is, I suggest, unsatisfactory. Here's why. <!--break--> First, I question the reason given for omitting comments. The choice was made to leave comments out because some people were doing things with them that Crockford didn't like. If there is good reason to disallow parsing directives, might the first step be to state in the specification that parsing directives are disallowed? Then, at least, any standards-compliant implementation will not include support for those. But to throw out comment support to stifle an undesired use… it seems to me that this is a case of throwing out the baby with the bathwater. I hope nobody ever decides to put parsing directives in strings.
Second, there is an assumption in this answer that the person who wants comments is the same one who is programming the application, and can thus adjust by "just running jslint" or (as one commentator suggested) "just storing comments in __doc__ strings." In many cases I, the user of the program, do not have the ability to intercept a JSON blob at some crucial juncture where comments are no longer necessary and "real" processing is about to begin. Likewise, even if I could make the __doc__ solution meet both of the requirements I sketched above, as an application user I cannot modify the expectations of the application regarding what data is contained in a JSON blob.
As a JSON user, I would really like comments in JSON. And I would like this without the added requirement that I build a tool chain to preprocess every JSON file to strip such content.
