10 ms·
Douglas Crockford: Why I removed comments from JSON
- andyl 15y agoLack of comments in JSON is a bummer. But it is easy enough to pipe the JSON thru a filter...
- Someone 15y ago...and before you know it, your system that is built using various third party libraries contains 'JSON' files with various comment conventions: - # in column 1 - # in column 1, backslash at end of line escapes the newline - # as first non-blank - # as first non-blank, backslash at end of line escapes the newline - -- as first non-blank - C-style multi-line slash-asterisk comment asterisk-slash - C++-style // - Python style doc strings etc. Then somebody will attempt to write the comment filter that will handle them all, somebody else will make a JSON parser that round-trips all different versions. Net result: a JSON 'standard' that is ugly and leads to parsers that are larger then necessary, not 100% reliable (how do you guess whether a backslash at the end of line escapes the newline?) I would rather have a simple standard with one kind of comment.
- drivebyacct2 15y agoWell at least there aren't semicolons in JSON.
- anonymoushn 15y agoOtherwise we might run into a bug in JSMin!
- generateui 15y agoI followed the little uproar about the JS semicolon. I do wonder though, did it became a running joke because of Twitter, or the developer rejecting them? (rejecting the not-use, I mean)
- burgerbrain 15y ago> "I saw people were using them to hold parsing directives" What could possibly make somebody want to do that? Are there any examples around of people doing that?
- Yarnage 15y agoI completely believe him. Even though XML is really verbose I saw quite a few folks adding these types of things in XML comments. So this wouldn't surprise me one bit. Would be interesting to see some real-world examples though.
- wmil 15y agoThe CDDB/FreeDB format requires you to parse comments... http://www.jwz.org/doc/cddb.html http://www.jwz.org/doc/cddb.html And people do all kinds of nonsense with HTML comments. A very bad idea is often the fastest to implement.
- mcav 15y agoAnd so instead, people embed parsing directives in the JSON itself.
- jerf 15y agoYes, but that works. Taking in such JSON and then immediately spewing it back out doesn't change the underlying meaning. Transforms from such JSON to some other format (perhaps even another JSON format) must explicitly choose what to do with "comments", instead of accidentally just discarding them. Given that parsing directives are going to exist somewhere, this is the correct place for them. (Better yet is to create an explicit place for metadata. I almost reflexively use {"metadata": null, "payload": ...} now instead of putting my payload right at the top level, because wouldn't you know it, sooner or later some metadata always seems to wander in. And if it doesn't... shrug. If you're in a place where you can afford JSON in the first place the extra cost is probably way below the noise threshold for you.)
- mcav 15y ago
- DTrejo 15y ago{ "//": "I approve of the choice to omit comments from JSON." }
- generateui 15y agoI was exactly thinking this when I was halfway reading the article. "Why not just add a property as comment?"
- Yarnage 15y agoArticle? It's only 5 short sentences and the idea to add it as a property is the first comment on the post.
- generateui 15y agoArticle, blogpost, same thing. The first sentence is > I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I do not read something on the lines of "you can also use a comment as a property". I wonder how you read that in the first sentence?
- kcbanner 15y agoHe said first comment, not first sentence.
- Yarnage 15y ago>> I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. >I do not read something on the lines of "you can also use a comment as a property". I wonder how you read that in the first sentence? lol, please re-read my comment. I said the first COMMENT, not sentence, had the same suggestion. :)
- tolmasky 15y agoThere are many good reasons not to add documentation as properties. For starters, it is a very US-centric approach to things. I would probably be annoyed if I was using a foreign language library that had random strings which contained text I did not understand in my objects. Secondly, the second you start putting documentation in your JSON, be prepared for services to break if you ever change that documentation. It may be silly to do "if (json._doc_.indexOf...)", but stranger things have happened and if you are making an API it is generally a bad tactic to require your clients not to be silly. "But I intend to have it in there solely because I can't use real comments -- I don't plan on shipping these". OK then probably no problem -- but at this point they're really no better than normal comments (with respect to the issue that Crockford brings up) since theres no reason you can't put compiler directives in the "comment" properties: { /* do something special mr. proprietary compiler */ "compiled_property": "magic" } vs. { "//" : "do something special mr. proprietary compiler" "compiled_property": "magic" } So the possibility of diverging incompatible implementations remains -- however I think the real reason this didn't happen wasn't the lack of comments but rather that JSON's biggest selling point is almost universal compatibility.
- kevincennis 15y agovar crockford = function(){ while(1); }
- Yarnage 15y agoError: Problem at line 1 character 25: Expected exactly one space between 'function' and '('. var crockford = function(){ while(1); } Problem at line 1 character 27: Expected exactly one space between ')' and '{'. var crockford = function(){ while(1); } Problem at line 1 character 27: Missing space between ')' and '{'. var crockford = function(){ while(1); } Problem at line 1 character 29: Missing 'use strict' statement. var crockford = function(){ while(1); } Problem at line 1 character 34: Expected exactly one space between 'while' and '('. var crockford = function(){ while(1); } Problem at line 1 character 35: Unexpected '1'. var crockford = function(){ while(1); } Problem at line 1 character 37: Expected exactly one space between ')' and ';'. var crockford = function(){ while(1); } Problem at line 1 character 37: Missing space between ')' and ';'. var crockford = function(){ while(1); } Problem at line 1 character 37: Expected '{' and instead saw ';'. var crockford = function(){ while(1); } Problem at line 1 character 37: Unexpected ';'. var crockford = function(){ while(1); } Problem at line 1 character 39: Cannot convert 'array[0]' to object
- user-id 15y agoProblem at line 1 character 39: Cannot read property 'disrupt' of undefined Huh?
- kevincennis 15y ago'disrupt' is an internal thing. There's a try/catch somewhere that's failing, but he catches the error and adds it to JSLINT.errors as if it were a problem with YOUR code.
- TazeTSchnitzel 15y agoIt was probably an innocent mistake, he most likely put it there for debugging.
- Yarnage 15y agoThis makes sense to me. JSON is designed to simply hold data so there shouldn't need to be any comments. If it's related to configuration then there should be documentation regarding what is and isn't supported. If it's simply data you're sending across the wire then there should be documentation somewhere; you wouldn't want to waste bandwidth transmitting comments.
- nirvdrum 15y agoIt's fairly common to annotate that data. While every entry in my postgresql.conf file is documented someplace, it'd be an absolute nightmare if defaults couldn't be commented inline or if I couldn't relay why a value is set to a particular value by adding a comment. Note in this case, nothing would be transmitted over the wire. JSON is just being used as a convenient format. Even still, it can be handy to exchange annotated data over the wire.
- Yarnage 15y ago>It's fairly common to annotate that data. While every entry in my postgresql.conf file is documented someplace, it'd be an absolute nightmare if defaults couldn't be commented inline or if I couldn't relay why a value is set to a particular value by adding a comment. What happens when you accidentally delete a value you didn't mean to? You would refer to documentation. Honestly all configuration files _should_ be well documented, including postgres so I don't see the issue here. Why would you want to include every single possible option, probably commented out, when you could simply grab the ones you need from the documentation? I would prefer having a lean configuration file that shows exactly what I'm using rather than 400 commented options; that's a MESS to maintain. >Even still, it can be handy to exchange annotated data over the wire. I cannot disagree more. It is not useful AT ALL to exchange annotated data. Unless you're using an ad-hoc system (which obviously wouldn't scale), you're going to be handling this through APIs and services that already know and understand the JSON file format. So the only purpose of comments at this stage in the game is using up extra bandwidth.
- AlisdairO 15y ago
- warmfuzzykitten 15y agoComments about removing comments thus far seem to miss the point. By removing comments, he greatly simplified the parser. Since he was sure to be criticized for this design choice in the direction of simplicity, it was a brave decision! Had there been enough radical simplifiers on the XML committee, we might not have needed JSON. Wait... Committee? Never mind.
- burgerbrain 15y agoI have a hard time believing that the removal of comments would greatly simplify a JSON parser.
- mturmon 15y agoThere would have been demands for tools that transform JSON to JSON, or JSON to XML, to preserve comments across the transformation. Adding that capability would raise the complexity of the parser, because comments would have to be made part of the data structure that is built and transformed. For instance, it would be harder to embed the data structure for the JSON in JS objects. But yes, for a parser that's ingesting data for immediate processing and has no need for comments, there's no discernable win regarding parsing simplicity.
- gnuvince 15y agoGreatly simplified the parser? It's probably 10 lines of code.
- webignition 15y agoThat'll be 10 * K lines of code, where K is the underestimation factor. Not to mention N unit tests to cover comment removal verification.
- doomslice 15y agohttp://coding.smashingmagazine.com/2012/04/27/yahoos-doug-crockford-on-javascript/ http://coding.smashingmagazine.com/2012/04/27/yahoos-doug-cr... "One interesting story about leaving things out: as we got closer to releasing JSON I decided to take out the ability to do comments. When translating JSON into other languages, often times the commenting piece was the most complicated part. By taking the commenting out we reduced the complexity of the parsers by half—everything else was just too simple."
- rbanffy 15y agoWhy not simply add "comments will always be ignored, any JSON parser that assigns semantic value to them is non-compliant, every time it's used baby Cthulhu cries and the sad soul who wrote it will burn in hell for eternity" to the spec? This more or less prevent anyone from using JSON for configuration. Unless, of course, you parse it with eval.
- TazeTSchnitzel 15y agoYou're assuming people will take his advice. By removing them, he ensured nobody would use them, at least for "pure" JSON.
- sirclueless 15y agoWhat better way to accomplish that then to remove comments from the spec? There's nothing stopping a non-compliant parser from allowing them anyways, it's just that now it is abundantly clear that such a parser is non-compliant because it is "impure".
- burgerbrain 15y agoIt would be an improvement because then I could count on comments in JSON doing nothing (instead of possibly not parsing).
- hp 15y agoIt makes total sense to omit comments, because JSON is optimized for machine-readability and interoperability (simple spec, simple implementation, no extension mechanism, fast to parse). Putting comments in would compromise it for that purpose. JSON isn't a great config file format, if your config file is meant to be human-edited. But the solution is simple; use a format designed for human editing. Config files need UI design too. During Akka and Play 2.0 development, we approached this by starting from the hand-rolled parsers found in Akka 1.2 and Play 1.2 (both had ad-hoc parsers to support a "pretty" config file format). We took the aesthetic preferences of the hand-rolled parsers seriously, and came up with HOCON: https://github.com/typesafehub/config https://github.com/typesafehub/config (scroll down to "JSON Superset"), https://github.com/typesafehub/config/blob/master/HOCON.md https://github.com/typesafehub/config/blob/master/HOCON.md The HOCON format is a superset of JSON and also happens to be mostly compatible with the Play and Akka 1.2 ad hoc parsers (which were independently developed, so two data points on what people wanted). HOCON is roughly similar to YAML in complexity. Like YAML the spec is pretty long ( http://www.yaml.org/spec/1.2/spec.html http://www.yaml.org/spec/1.2/spec.html ). And the Typesafe Config and SnakeYAML jars have pretty comparable amounts of bytecode in them. HOCON or YAML would be terrible formats for an API or something like that, and they're painful to implement, but I strongly prefer them to JSON for human-maintained configuration. Anyway, I think the genius of JSON was its focus on machine interoperability rather than trying to do everything, that's why it works so well for machine interoperability. But it doesn't mean you have to use it for everything.
- gnuvince 15y agoFrom json.org: "JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate." Humans are mentioned before machines. Comments improve human readability. Furthermore, comments are very simple to implement, and don't lower the ease of parsing.
- philjohn 15y agoAnd as Crockford said, if you want comments in your JSON, knock yourself out - just strip them out before handing it over to your parser.
- avstraliitski 15y agoJSON Schema supports 'title' and 'description' for each field - however, there is no internationalization. Certainly, commenting on a schema is more meaningful than commenting in a regular payload-style data structure.
- dap 15y agoAs several people have pointed out, this doesn't make a lot of sense. People could just as well put parsing directives in special properties. On the other hand, having proper comments would make using JSON for configuration significantly nicer. It would also allow you to have JSON snippets that themselves are documented, as when documenting a JSON web API. Using properties as comments is awkward at best: it doesn't match what people are used to, either the key or value ends up being a dummy, and consumers that iterate over properties have to be smart enough to ignore special doc properties (which can make automatic validation against a schema more difficult). The solution of running it through JSMin is pretty unsatisfying too. It's never wrong, so how about we always do that?
- lurker721 15y agoConsider these two paraphrased arguments against Crockford, each made independently by many poster-programmers here: (1) I don't like comments, but removing them won't solve anything: People who like comments can just embed them as funky properties. (2) I like comments, but embedding them as funky properties is annoying and awkward, and I don't want to. Now look at (1). Now look at (2). Now relax your eyes like you're looking at a stereoscopic poster until (1) and (2) merge together and you achieve a Zen-like understanding -- or a view of a schooner.