729109 - Make sure synchronous XHR examples don't appear on MDN

Status: RESOLVED FIXED

(Developer Documentation Graveyard :: API: DOM, defect)

Description

[Henri Sivonen (:hsivonen)]

Synchronous XMLHttpRequest is among the most painful parts of the Web platform. Even though its existence is kinda Mozilla's fault (for cloning even the bad parts of Microsoft's initial XHR) and even though we can't completely remove support, we shouldn't suggest to Web developers that it's something they might use. When Web developers use synchronous XHR, they tickle bad bugs in Gecko and even when they don't tickle bugs, synchronous XHR is bad for the user experience, since it locks up the page.

Comment 1

[Luke Crouch [:groovecoder]]

Sheppy, Janet, Jean-Yves, can any of you work with Henri to decide if and how such advice might be worked into MDN docs?

Comment 2

[Eric Shepherd [:sheppy]]

Just because it's bad doesn't necessarily mean it shouldn't be documented. But we can strongly de-emphasize it.  What I'd probably do is change the "Synchronous and asynchronous requests" section to simply mention the existence of synchronous requests, but that they're a very bad idea, then move the docs for synchronous requests down to the very end instead of presenting them first.

Comment 3

[Olli Pettay [:smaug][[e-mail]]]

Note, sync XHR is bad in window context. Sync APIs are ok in workers.

Comment 4

[Mats Palmgren (inactive)]

"8.4% of all hangs in IE9 in the past month are caused by XMLHttpRequest objects blocking the UI thread with a synchronous request. That’s a huge number!"
http://blogs.msdn.com/b/wer/archive/2011/08/03/why-you-should-use-xmlhttprequest-asynchronously.aspx

We should have strongly worded advice to *never* use it other than in workers.

I think we should also mention that JSON-RPC is implemented using sync XHR and
thus you shouldn't use that on the UI thread either.  (bug 709746)

I think we should also edit the JSON-RPC wikipedia page to warn people of this footgun.
https://en.wikipedia.org/wiki/JSON-RPC

Comment 5

[Mats Palmgren (inactive)]

Also, I would like to see this advice directly in the spec too:
http://www.w3.org/TR/XMLHttpRequest/#the-open-method

Comment 6

[Henri Sivonen (:hsivonen)]

(In reply to Eric Shepherd [:sheppy] from comment #2)
> Just because it's bad doesn't necessarily mean it shouldn't be documented.

It's OK and honest to say that it exists (in the doc for the open() method). However, I think the doc should say never to use it outside Workers.

I think all examples that use XHR outside Workers should be async--preferably so that the third argument to open() is omitted to avoid drawing attention to the fact that passing a different boolean is a possibility.

Comment 7

[Eric Shepherd [:sheppy]]

We've done a good bit of work on this over the last year or so, and I just now swapped sync and async so the latter is listed first in the docs, so I'm marking this fixed.

Comment 8

[Mats Palmgren (inactive)]

The example in "Handling responses" still use sync XHR:
https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest
The chosen example and the text after it: "There are some situations where the
contents of a remote response from an XMLHttpRequest may not be handled as easily
as the case above." strongly suggests that sync XHR is the preferred way and
there is no mention of any problems with it whatsoever.  :-(

The sync examples needs to be removed ASAP (there's two more further down).
It would be nice to have a simple boiler plate async example in its place.

Again, in the API documentation there's no mention of any problems with using
sync XHR.  It should have STRONGLY worded text that sync XHR should be avoided
like the plague it is.
https://developer.mozilla.org/en-US/docs/DOM/XMLHttpRequest

I would prefer if the Using_XMLHttpRequest page didn't even mention sync XHR.
As Henri said, we can simply omit the third arg in the examples.
We already link "open()" to the API page for anyone wanting further info.

Comment 9

[Florian Scholz (Open Web Docs)]

There is now https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest#Types_of_requests and https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/Synchronous_and_Asynchronous_Requests which talk about async and sync request types. Please open a new bug if there are still specific problems with the current XHR MDN docs.

Comment 10

[Henri Sivonen (:hsivonen)]

(In reply to Florian Scholz [:fscholz] (MDN) from comment #9)
> There is now
> https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/
> Using_XMLHttpRequest#Types_of_requests and
> https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/
> Synchronous_and_Asynchronous_Requests which talk about async and sync
> request types. Please open a new bug if there are still specific problems
> with the current XHR MDN docs.

I changed "In general, you should rarely if ever use synchronous requests." to "Do not use synchronous requests outside Web Workers." in order to make this bug FIXED.

Comment 11

[Chris Mills [:cmills]]

I'm not sure you meant to reopen this. If you did, please clarify what else is needed.

Comment 12

[Henri Sivonen (:hsivonen)]

Sorry, I first put the Bugzilla form to reopened state, but before submitting, I went ahead and edited the wiki myself instead.