Hacker News Reader

Comment by DTrejo | Hacker News Reader

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

View on HN

(which any competent parser would handle just fine.)

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

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

Article, 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?

He said first comment, not first sentence.

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

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.

It's not US-centric. It's English-centric and English is the lingua franca of software engineering as it is with many other professions. TBH, programming is and will always will be English centric and I would never feel 100% confident with any software engineer that isn't very proficient in English insofar as reading and writing are concerned. Practically every tome, text, blog or article of any real value in the field is published in English, and only once they are really well known are they translated to other languages. The only time the English speaking programming World is behind that of another language is when a new language is developed by a non-native English speaker (such as Lua developed in Brazil and Ruby developed in Japan). And even then no language would ever see popular adoption to the point of importance if it doesn't adopt English as the language of its source and its documentation.

This isn't bigotry. This is just the way things are.

FWIW, English isn't my first language, Portuguese is, but I have native fluency in English.

To add to this, I suspect any non-English speaker would rather have English comments that they can at least throw at Google Translate, than no comments at all.

From my work with Taiwanese engineers, I have found that reading and writing are as much two different skills as speaking and listening are.

Almost all of them can read English remarkably well, but some of the emails I get from them... Often grammar and syntax are nowhere to be found, and the vocabulary is occasionally amusing (a couple of the memorable gems have been "USB sticker", presumably thinking of "USB stick" (and still ambiguous in the context of the message, what they were talking about was a USB WiFi dongle), and "redeploy" referring to a reboot or power cycle).

> This isn't bigotry. This is just the way things are.

Indeed, I don't think this situation is all that different from Medicine or Biology. Parts of anatomy, diseases, and taxonomic classifications will forever be known by their Latin names. Likewise, programmers will probably still be referring to "if" statements and "for" loops long after no English speakers remain.

> Likewise, programmers will probably still be referring to "if" statements and "for" loops long after no English speakers remain.

Or, in reverse; I knew what those words did in BASIC before I knew what they meant in English (which isn't my native language).

Same here :)

    ... will always will be English centric ...

I don't think you can claim that. Maybe for the next few decades or centuries but beyond that who knows what will happen.

    Practically every tome, text, blog or article of any
    real value in the field is published in English ...

Is it possible that you just don't know they exist? You probably don't know enough to make such claims, as an English speaker myself, I know of a few books that I would want to read but they haven't been translated yet. There aren't many, but then again I don't know about others because of me not knowing the language.

That do not match my experience in a Chinese Web company. All my colleagues are very good hackers but only some of them are confident at writing English. Most important literature is translated in Chinese, and they prefer reading translated versions. Comments in the code are in Chinese. It is sometime a bit more difficult for us for variables and functions names but it works.

I would agree that a good coder must be able to express clearly and unambiguously complex processes in mother tongue and his programming language of choice but excellent grasp of English is only a "nice to have", when your local community is developed enough.

I don't really see that these are valid concerns. It's not really a US-centric approach - you'd have the same issues with comments. If you were concerned about internationalizing documentation, then you could easily get around this by making the property name localized and store the documentation in the appropriate language property.

As for breaking services - you could make these JSON parameters optional and very clear that the documentation won't affect the way the service runs.

If you have documented the API sufficiently, then it's not a bad tactic to require clients "not to be silly". Clients who misuse APIs can't complain if they don't use them properly.

How about this?

    {
    "// compiled_property" : "do something special mr. proprietary compiler"
    "compiled_property": "magic"
    }

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.

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

Reply on news.ycombinator.com