4 ms·
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 w
by tolmasky 15y 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.
- malandrew 15y agoIt'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.
- burgerbrain 15y agoTo 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.
- nknight 15y agoFrom 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).
- jballanc 15y ago> 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 15y ago> 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 15y agoSame here :)
- mangodrunk 15y ago... 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.
- chris_wot 15y agoI 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 15y agoHow about this? { "// compiled_property" : "do something special mr. proprietary compiler" "compiled_property": "magic" }