Why Microsoft Can't Write Good Error Messages

One of my pet peeves is that there is so much software out there with bad error messages, and much of it seems to come from Microsoft. To be sure, there are many other companies just as guilty of writing poor diagnostics, but Microsoft is such a big part of all our lives, and it is fun to pick on them. Here's a 20 year old joke I still love tell...

There is this helicopter flying towards Seattle Airport, but it is very foggy. Eventually he sees a tall building projecting above the clouds and flies over for a look. He spots someone on the roof and hovers near, opens the window and shouts "WHERE AM I?" The person on the roof shouts back "YOU ARE IN A HELICOPTER!" The pilot immediately takes off west and in a few minutes lands safely at the airport. The passenger looks at the pilot and says "how did you know where to go?" The pilot says "well his answer was 100% correct, and 100% useless, so I figured he must work for Microsoft. From there I knew which way Seattle was."

I really hate doing software development in Microsoft-land, Visual Studio, .NET, COM, Microsoft C++, and all that crap. I find I am far more productive using Eclipse, Java, and open source artifacts. What I really hate is when something is not working, the diagnostic messages are incredibly poor or even nonexistent. One day I was working on a hard problem and could make no headway, so I asked a teammate with more Visual Studio experience for some help. He said just step through your program with the debugger. I took his advice, and eventually I found the problem because I reached a point in the debugger where an error result appeared that I have never seen emitted before. The point was, the only way to solve the problem was with the debugger, the error result was not logged or emitted in any place outside of the debugger.

My teammate told me that when developing Microsoft applications you have to spend a lot of time in the debugger, everyone does, it's just what you have to do.

This was quite alien to me. I have used debuggers before, but I only used them as a last resort. I prefer to rely on logging messages, because when you are troubleshooting you do not always have a debugger - for example at a customer site.

It finally occurred to me there are two camps of thought on this: one camp, the one I am in, only uses debuggers as a last resort; while the other camp always uses the debugger as a first resort. Here is what happens

• When you avoid using the debugger you tend to write a lot of logging messages for diagnostic purposes. When troubleshooting you write even more messages to zero in on the problem, until it becomes clear what the code is actually doing. What you have done is to codify your diagnostic process into the software itself. The more you do this, the more experienced you get at writing better and better messages. When you are really experienced, your messages not only tell you clearly what the problem is, but often how to fix the problem as well. For example, a message that says "can't find configuration file foo" is like that guy standing on the roof of the Microsoft building. On the other hand, a message that says "MyApp.Configurator cannot find the file C:\Program Files\My Application\web\data\foo.xml" is a lot more meaningful. When it comes to writing user facing error messages I also find that the people in this camp are much better at producing these types of messages too, because the more diagnostic messages you write, the more logs your read, the more crappy messages you find, the better you get at writing clear and meaningful messages.
• When the debugger is your first resort at solving a problem, you step through the code, you think about the problem, you reason stuff out, and eventually you find the solution and move on. All that reasoning and problem solving wisdom from that moment does not get written down anywhere for anyone else to see or learn from. Even if you have to revisit the same problem months later you have likely paged-out how you figured out the problem in the first place, and have to reinvent the reasoning from scratch. Also, because you are never writing any diagnostic messages, you don't get any good at writing diagnostic messages. When you are forced to write some user facing diagnostic messages because there requirements mandate it - well, you are still a neophyte moron when it comes to writing diagnostic messages - your are just that guy standing on the roof of the Microsoft building.

To be fair, I reiterate Microsoft are not the only one's guilty of this practice, I have seen this time and time again over the years in Unix and Mac OS, and open source software, etc. Also to be fair, when I am working in Java culture, I do notice the diagnostic messages generally are better than I see in other cultures.