[tolmasky]

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.

[malandrew]

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.

[jballanc]

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

[mseebach]

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

[kolinko]

Same here :)

[mangodrunk]

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

[burgerbrain]

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.

[gbog]

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.

[nknight]

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

[chris_wot]

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.

[inexplicable]

How about this?

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