Douglas Crockford: Why I removed comments from JSON

https://plus.google.com/118095276221607585885/posts/RK8qyGVaGSr

by mmastrac • 14 years ago

130 100 14 years ago

plus.google.com

andyl• 14 years ago

Lack of comments in JSON is a bummer.

But it is easy enough to pipe the JSON thru a filter...

Someone• 14 years 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• 14 years ago

Well at least there aren't semicolons in JSON.

anonymoushn• 14 years ago

Otherwise we might run into a bug in JSMin!

generateui3• 14 years ago

I 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)

burgerbrain4• 14 years 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?

Yarnage14• 14 years ago

I 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• 14 years ago

The CDDB/FreeDB format requires you to parse comments... 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.

mcav3• 14 years ago

And so instead, people embed parsing directives in the JSON itself.

jerf2• 14 years ago

Yes, 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.)

famousactress• 14 years ago

It's not hard to imagine if you sorta hold your breath and let yourself get a little dizzy and think hard about XML you've had the pleasure of messing with.

I quickly get visions of version numbers, customized namespace declarations, typedefs, strftime date format strings...

kuahyeow• 14 years ago

or say Javadoc @ directives....sigh

mikeash2• 14 years ago

Not JSON, but here's a truly horrible example of Internet Explorer using specially formed comments to take different actions: http://www.quirksmode.org/css/condcom.html

devicenull• 14 years ago

They really aren't that bad, definitely very handy for injecting IE specific stylesheets, without having to rely on javascript.

Nagyman• 14 years ago

This brings to mind Closure Compiler's use of comment annotations to add type checking, etc to javascript.

https://developers.google.com/closure/compiler/docs/js-for-c...

pavel_lishin2• 14 years ago

Symfony2 offers it as a possibility: http://symfony.com/doc/current/book/doctrine.html#add-mappin...

jhaglund• 14 years ago

Yep, it made me rage a bit when I found that in a project I'm working on. Comments are for people, people!

tolmasky2• 14 years ago

You can imagine something like this:

    {
       /* if IE */
       browser: "IE"
       /* else */
       browser: "standard"
       /* endif */
    }

Pretty terrible and still possible (but admittedly harder) without comments.

greghinch• 14 years ago

If you are storing this kind of implementation logic in your data, I hope I never have to work with you (not aimed at parent posting, but rather the global "you"

chris_wot4• 14 years ago

Happens already. Two examples:

1. Internet Explorer has conditional comments - http://msdn.microsoft.com/en-us/library/ms537512%28v=vs.85%2...

2. Sprockets' directive processor uses directives in comments. https://github.com/sstephenson/sprockets

endgame• 14 years ago

Weren't pascal comments delimited by `{` and `}`, and weren't borland pascal compiler directives of the form `{$X}`?

kabdib• 14 years ago

Yes, this was pretty common in Pascal.

Also, Emacs uses comments to set file-local options. There's a long tradition of overloading comments to achieve metalinguistic ends. JavaDoc and Doxygen are great examples.

Even when handed a decent macro language with whizzy namespaces and a great DOM, I imagine that some people will still stoop to gross and convenient hacks.

frobozz• 14 years ago

Here's an example of using javascript comments to set options on a parser. It isn't JSON, but it is pertinent.

/* jslint nomen: true, debug: true, evil: false, vars: true */

mseebach3• 14 years ago

As others have pointed out, this is fairly common, but no-one seem to have pointed to this one:

http://en.wikipedia.org/wiki/C_preprocessor

pyre• 14 years ago

The C preprocessor processes comments?

DTrejo• 14 years ago

    {
      "//": "I approve of the choice to omit comments from JSON."
    }

generateui3• 14 years ago

I was exactly thinking this when I was halfway reading the article. "Why not just add a property as comment?"

Yarnage14• 14 years ago

Article? It's only 5 short sentences and the idea to add it as a property is the first comment on the post.

tolmasky2• 14 years ago

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

mcav3• 14 years ago

(which any competent parser would handle just fine.)

dlubarov• 14 years ago

What if you need to encode arbitrary dictionaries, which may have keys like "//", rather than objects with specific named attributes?

And what if you want multiple comments in the same scope (say, a comment before each attribute)? From the RFC: "The names within an object SHOULD be unique." In practice parsers will just override values, as JS does, but I think it would be legal to reject JSON with duplicate keys.

polemic• 14 years ago

IMHO, the complexity that this would introduce just highlights why it's a good idea not to have them.

> "but I think it would be legal to reject JSON with duplicate keys."

No it would not. `SHOULD` has a very specific meaning:

  SHOULD   This word, or the adjective "RECOMMENDED", mean that there
    may exist valid reasons in particular circumstances to ignore a
    particular item, but the full implications must be understood and
    carefully weighed before choosing a different course.

See http://www.ietf.org/rfc/rfc2119.txt

An object with duplicate keys must be parsed, but the exactly result will be implementation specific (undefined).

kevincennis2• 14 years ago