Don't recommend domains for error handling

[benjamingr]

This PR closes #2055 by removing the suggestion to use domains for exception handling. Additionally clarify unhandledException a bit.

PR-URL: #2056

[trevnorris]

Not saying it's not, but it should be clear that unhandledException should not be used for error recovery.

[benjamingr]

Do not use it as the io.js equivalent of On Error Resume Next. An
unhandled exception means your application - and by extension io.js itself -
is in an undefined state. Blindly resuming means anything could happen.

Think of resuming as pulling the power cord when you are upgrading your system.
Nine out of ten times nothing happens - but the 10th time, your system is bust.

Improvement suggestions? Seems az clear as it gets to me :)

[targos]

The "On Error Resume Next" is a strange to me. I understand what it means but I had to google to know it is a VB concept.

[benjamingr]

@targos , I actually didn't change that part but I quite like it, I understood it but I never professionally did VB. I don't mind changing it while I'm at it if you have a suggestion :)

[albertorestifo]

What about:

Do not use it as an error handling middleware.

[benjamingr]

I'd rather not impose words like middleware that not everyone knows on the documentation, if someone is just now exploring what unhandledRejection is I'm not sure they'd understand that.

[albertorestifo]

Agree. What about:

Do not use it to attempt error recovery. An unhandled exception means your application - and by extension io.js itself - is in an undefined state. Blindly resuming means anything could happen.

[benjamingr]

@albertorestifo

An unhandled exception means your application - and by extension io.js itself - is in an undefined state. Blindly resuming means anything could happen.

Think of resuming as pulling the power cord when you are upgrading your system. Nine out of ten times nothing happens - but the 10th time, your system is bust.

You have been warned.

This seems pretty strong already to me. Wouldn't you agree?

[albertorestifo]

@benjamingr 👍

[benjamingr]

Can anyone else LGTM and/or merge it?

[trevnorris]

LGTM

[reqshark]

+1

[reqshark]

this sounds right but I might say:

Handling this type of exception recognizes an unrecoverable problem with the application, at which point it is time to both: restart the application and investigate further.

[benjamingr]

"Recognizes an unrecoverable problem" sounds a bit unclear to me, do you mind rephrasing?

[reqshark]

hmm, if that's unclear, I guess the main point there is that such an exception shouldn't be held out as a crutch to blindly restart applications, carrying on as if nothing happened, but rather an occasion to re-evaluate some area that is unfinished or very likely broken

[benjamingr]

Sorry for the time it took, squished, added Reviewed-By to commit message.

[trevnorris]

Landed with git commit message fix, and removal of trailing whitespace on 0f09b8d.