Design Guidelines Update: Exception Message Guidelines

re: Design Guidelines Update: Exception Message Guidelines

Alan McBee — Thu, 29 Jan 2004 07:34:00 GMT

What I think would be more helpful would be if the exception always carried some kind of identifier (yes, I know it's a pain to uniqueify those) that allowed me to quickly query on all KB articles, or google for pages that discuss solutions. The uniquer, the better. (Don't throw a dictionary at me, please.) I've spent too many times trying to find the KB article for an error by the text of the error message, only to find the answer in a newsgroup where the error message was misttyped by someone who couldn't cut&paste the exception message from the dialog box/offending web page.
->A

re: Design Guidelines Update: Exception Message Guidelines

RichB — Thu, 29 Jan 2004 07:58:00 GMT

Any chance you could encourage the IE team to use this advice too. According to this KB article, a new patch to IE preventing username-prefixed URLs and will display the following error message:

Invalid syntax error

http://support.microsoft.com/default.aspx?id=834489

re: Design Guidelines Update: Exception Message Guidelines

Pavel Lebedinsky — Thu, 29 Jan 2004 08:13:00 GMT

> Do localize exception messages

I'm probably in the minority here, but I disagree with that.

When you talk about "users", do you mean end users, programmers, IT/support people or somebody else?

For end users, it's going to be a horrible user experience if you start showing them raw exception messages, translated or not. No matter what the guidelines say, there will always be components that use bad/cryptic messages so the best approach for end user applications is to display their own localized errors for exceptions that the application recognizes, and a generic error dialog for everything else. This dialog could have a "Technical Details..." button that would show things like description and stack trace (which for troubleshooting purposes is just as useful as description, if not more).

For programmers and other technical people localized messages are mostly an annoyance (I'm not a native English speaker so I have some first hand experience with this). To be able to program in .NET you need to understand things like class names anyway, so it's very unlikely you will have problems understanding exception messages.

However when you need to troubleshoot a problem for a user and all you have is a Russian exception message from the user's computer, it's very unlikely that MS KB search (or even google) will tell you anything.

Also, what about situations like remoting where exceptions can be raised by server code and handled by clients who have different language settings?

May be it would be useful to have something like an optional interface that could be used to extract user-friendly, localized descriptions from an exception object, but I think that forcing all exceptions to be localized is wrong.

re: Design Guidelines Update: Exception Message Guidelines

Ken Brubaker — Thu, 29 Jan 2004 14:04:00 GMT

Identifier

I specify the use of identifiers for exceptions in my application architectures. But such a requirement is probably best left at the application/enterprise level rather than the base system level. The only reasonable way to have globally unique error codes would be to use guids, but they would be very difficult to communicate on a support call or KB-type look up.

New exception message guidelines

Ken Brubaker — Thu, 29 Jan 2004 17:11:00 GMT

re: Design Guidelines Update: Exception Message Guidelines

Micael Baerens — Thu, 29 Jan 2004 14:28:00 GMT

What about a guideline about allways specifying which resource caused the exception, if any?

So instead of:
"File was not found."

then:
"File 'c:\myfile.txt' was not found."

It makes it a lot easier to troubleshoot.

Design guidelines from Microsoft

James Geurts' Blog — Thu, 29 Jan 2004 18:26:00 GMT

re: Design Guidelines Update: Exception Message Guidelines

Brad Abrams — Thu, 29 Jan 2004 15:40:00 GMT

Alan -- yes an identifier is a good idea, I will pass on the suggestion. Although, Ken's point may pan out to be the only way..

Rich -- I hear you! I will pass on these guidelines (and your comments) to the IE team..

Pavel raises a good point -- The messages are mainly for developers, do you other developers feel like they want english only messages. The remotting\admin issue is a god one, maybe Alan's ID plan could help?

Micael has a good point, *if* you are going to put out a file name putting it in quotes is fine. But I will point out that could cause a security issue by giving out PII (Personally Idenitifable Information) such as user name to untrusted callers

re: Design Guidelines Update: Exception Message Guidelines

Jason Nadal — Thu, 29 Jan 2004 19:52:00 GMT

In RE: Do not personify (imply that programs think or feel).

I believe the term you are looking for is anthropomorphize (Although Word does think they're synonyms). Great list.

I'd also suggest not showing compiler errors to the user. For example, something like "a connection couldn't be made to a requested resource" instead of "resource error: object reference not set to an instance of an object".

re: Design Guidelines Update: Exception Message Guidelines

Jerry Pisk — Thu, 29 Jan 2004 20:11:00 GMT

As for IE refusing to use user name and password in a URL with "Invalid Syntax Error" - not only is the message cryptic, it's not even true - that syntax is valid as far as URLs go, it's just that IE decided not to support it.

re: Design Guidelines Update: Exception Message Guidelines

Ken Brubaker — Fri, 30 Jan 2004 18:38:00 GMT

Localization

I have written a framework to support different languages that interops with the event log API the way it wants to (It also supports multiple languages). It would be alot easier to dump that support, frankly. There IS one area where it is important, though.

I agree that end users should not see the errors: All consumer code oriented exceptions should be translated by the UI layer -- another reason to require an identifier. However, internal exceptions have TWO audiences, not just developers. Most internal errors get logged somewhere so that a sysop can look at them. Sometimes it it a coding problem and simply gets passed along to the developers. However some internal errors, i.e. non-consumer code errors, are environmentally driven and is the responibility of the IS admin to fix. These SHOULD be in the language of the installation culture.

New and Notable 36

Sam Gentile's Blog — Fri, 06 Feb 2004 17:00:00 GMT

re: Design Guidelines Update: Exception Message Guidelines

Jeff Gonzalez — Fri, 06 Feb 2004 14:01:00 GMT

I have a question, how was the decision for these 2 classes ctor parameters made...

Constructor for ArgumentNullException
public ArgumentNullException( string paramName, string message)

Constructor for ArgumentException
public ArgumentException( string message, string paramName)

re: Design Guidelines Update: Exception Message Guidelines

SBC — Sat, 07 Feb 2004 04:30:00 GMT

Provide extended messages (for certain exception types) -
for e.g.,
Also see KB Article: Q12345 or 76543:Info
(with the numerical code containing the hyperlink as a link label)

Exception Error Message Guidelines

William.Blog() — Mon, 16 Feb 2004 11:16:00 GMT

A compilation of new .NET Design Guidelines

Ken Brubaker — Fri, 20 Feb 2004 18:46:00 GMT

For my own reference, I thought I'd compile a quick list of design guidelines added by Brad Abrams, et al.

Microsoft Design Guidelines

James Geurts' Blog — Mon, 01 Mar 2004 20:34:00 GMT

More Design Guidelines

ExplosiveDog.Com — Thu, 04 Mar 2004 21:17:00 GMT

re: Design Guidelines Update: Exception Message Guidelines

Thomas Eyde — Sat, 06 Mar 2004 13:22:00 GMT

I had an SMTP mail issue in ASP.NET the other day. Try a search on 'Transporten kan ikke koble til serveren' or something like that, actual wording is forgotten. If I had the English equivalent 'The transport failed to connect to the server' it would be so much easier. I found it by coincidence when I searched on something else.

So localized system messages is not very helpful. I am a developer and didn't understand it, I don't think any local users would do either. Which comittee thought this was a good idea, anyway?

New and Notable 36

Sam Gentile's Blog — Fri, 12 Mar 2004 16:40:00 GMT

Custom Base Exception Class

Mark Treadwell — Sat, 27 Mar 2004 06:10:00 GMT

Custom Base Exception Class

Mark Treadwell — Fri, 02 Apr 2004 04:28:00 GMT

Custom Base Exception Class - V1 (VB)

.NET Hobbyist Programmer — Sun, 10 Jul 2005 06:21:08 GMT

More Design Guidelines

ExplosiveDog.Com — Sun, 14 Jan 2007 01:30:54 GMT

I was looking at BradA's blog again today and I saw his annotations for proper exception messages. This

Methods In Excel » HumanComputer Interfaces. Problems with messaging - Part 3

Methods In Excel » HumanComputer Interfaces. Problems with messaging - Part 3 — Thu, 22 Feb 2007 13:34:58 GMT

PingBack from http://www.blog.methodsinexcel.co.uk/2007/02/22/humancomputer-interfaces-problems-with-messaging-part-3/