Documentation

[Kuciwalker]

You do your documentation in JSON? :quizzical:

[Asher]

Much of my code is, but you can't rely on that. The project I'm working on now has forty full-time software developers in three cities and three timezones. The documentation required is pretty strict, and it's reviewed before any code commits to the repository as performed. While things like class diagrams, functional hierarchy, etc are auto-generated...there are requirements to provide formatted documentation (Doxygen) for methods and classes. As well as in-line documentation where needed, if it's not immediately obvious from the variable names and code structure.

It's amazing how much easier the system is to work with when the team leads are nazis when it comes to documentation.

[Hauldren Collider]

You do your documentation in JSON? :quizzical:

Data interchange, idiot . Back me up on this, you showed it to me

[Asher]

WHOOOOSH

http://json.org/

JSON is very useful also for web services. At my last job, our native data API was in XML but I wrote a XML-to-JSON bridge service in PHP also. Google, Microsoft, Yahoo, and other partners opted to use the XML interface for our data as XML is awesome. But for mobile devices (which is more bandwidth-conscious), we used the JSON service which was 20-30% smaller in filesize.

But JSON has a ton of problems with it, specifically with encoding. You also have to be far more vigilant with defensive programming when using JSON. And the JSON encoder/decoder libraries are usually much slower than the XML ones.

It's also far easier to communicate with vendors & teams by sending out an XSD than trying to document JSON structure.

[Kuciwalker]

We have 2 part-time developers (me and one of the consultants) and most of the stuff we maintain is just tomcat+mysql timesystem/portal type stuff. The one bit of code I have that isn't an incredibly standard mvc pattern is also designed to be written once and then never altered.

[Hauldren Collider]

So, JSON versus XML/DOM:

1. Verbosity
JSON is as verbose or not verbose as you want it. XML has closing tags. ****ING CLOSING TAGS. WHY.
JSON does not have attributes. There is no point to attributes if you're just trying to send data structures.

2. Interchange
XML sucks for interchange, and it is only possible because a lot of people spent a lot of time writing this horribly ****ty interface known as DOM that is in all languages. JSON already IS in all languages in some form or another, you just have to translate it a little bit and BAM. It is even LITERAL javascript and I think literal python, even.

3. Simplicity
JSON is a very simple tree data structure. XML is sort of this half-aborted B tree with its attributes and namespaces and text nodes and oh god oh god.

4. Extensibility
Who the **** cares about this? And WHY? Make a spec and keep it

5. Namespaces
SEE FOUR. WHAT THE **** IS THIS ****.

[Asher]

is also designed to be written once and then never altered.

Whoever "designed" that should be fired.

[Hauldren Collider]

But JSON has a ton of problems with it, specifically with encoding. You also have to be far more vigilant with defensive programming when using JSON. And the JSON encoder/decoder libraries are usually much slower than the XML ones.

You can serialize just about any heirarchy of primitives (IE A CLASS) into JSON easily. You can also prevent bad code from being run with 4 (that's FOUR) regexes that you can copypasta from anywhere and shove in a method and you're done.

[Asher]

I don't think you fully understand DOM if you're comparing it with JSON.

So, JSON versus DOM:

1. Verbosity
JSON is as verbose or not verbose if you want it. XML has closing tags. ****ING CLOSING TAGS. WHY.

Readability, helps ensure data integrity at the parser level and isolate errors. Try missing a bracket in JSON and debug that.

JSON does not have attributes. There is no point to attributes if you're just trying to send data structures.

Attributes are a powerful tool. With them you don't need closing brackets explicitly, either. Eg, <element attr="blah"/>

2. Interchange
XML sucks for interchange, and it is only possible because a lot of people spent a lot of time writing this horribly ****ty interface known as DOM that is in all languages. JSON already IS in all languages in some form or another, you just have to translate it a little bit and BAM. It is even LITERAL javascript and I think literal python, even.

This really doesn't make any sense. XML has rigid schema definitions which makes it ideal for interchange. JSON is ad hoc. JSON is most certainly not in all languages in some form or another (unless you count the free JSON.org libraries). This is also true for XML in all important languages.

"translating it a little bit" should never have to be done in a real data interchange format.

3. Simplicity
JSON is a very simple tree data structure. XML is sort of this half-aborted B tree with its attributes and namespaces and text nodes and oh god oh god.

Its simplicity is a strength and a weakness. It's great for small, quick things with simple formats.

At my last job, our nightly batch process uploaded 2-3GB XML files nightly. Can you imagine trying to parse a 2-3GB JSON string?

4. Extensibility
Who the **** cares about this? And WHY? Make a spec and keep it

If you have to ask, you just haven't run into it yet. It makes life a helluva lot easier.

When I had to syndicate video data across 20 different online video platforms, I defined an XML schema and published it then sent it to all of the sites. Programmatically, they used tools to import our schema and add it to their translation engines -- within a few minutes they hooked up a data transformation from our XML format to their internal XML format. If we had used JSON for this, it'd have been a nightmare and require a manual parser to be implemented.

5. Namespaces
SEE FOUR. WHAT THE **** IS THIS ****.

You don't understand the purposes of namespaces?

I think it's abundantly clear you've simply not encountered any problems that suit XML. That's not too surprising, considering they're usually bigger in scope and interoperability than most people experience before they graduate.

Do you think Microsoft should've implemented XAML in JSON instead of XML, by the way?

[Kuciwalker]

Whoever "designed" that should be fired.

It's a jsp designed to display a fixed set of immutable documents (spreadsheets) that all share a template. When a new template comes out each year, we aren't going to update the old ones, so we need the old jsp to hang around anyway.

[Asher]

You can serialize just about any heirarchy of primitives (IE A CLASS) into JSON easily. You can also prevent bad code from being run with 4 (that's FOUR) regexes that you can copypasta from anywhere and shove in a method and you're done.

I'm well aware you can serialize into JSON. I'm also well aware the problems this can cause, as I've run into them many times.

How do you specify which character encoding your JSON is using?

[Hauldren Collider]

Just assume UTF/8

Frankly most of the time people forget to put character encoding into XML ANYWAYS making your point moot.

[Asher]

Just assume UTF/8

Fail

Frankly most of the time people forget to put character encoding into XML ANYWAYS making your point moot.

It is ABSOLUTELY essential. If people forget, that's no excuse.

You've no idea how much of a nightmare this was for me. We supported English and French equally. We were talking to vendors who expected UTF-8, UTF-16, Latin-1, etc. It was an absolute mess, and JSON would've been a disaster in such an environment.

Also, I'm unaware of any databases with full JSON integration, while many fully integrate XML. It's hugely helpful.

[Asher]

There's a reason XML and JSON are both prevalent. They both serve different purposes and complement eachother.

JSON is more of a lightweight web-services format, XML is far more powerful and sports far more diversity in its usage. It's used in code commenting formats (as you've mentioned) -- try doing that in JSON?

It's used to describe interfaces (Android and WPF/Silverlight use XML to define the UI).

It's used to store/retrieve data from DBMS.

It's used to transfer massive amounts of data between systems.

It's used to translate data between systems quickly, easily, and safely.

etc.

[Kuciwalker]

Asher is, of course, correct.