How NOT to make a code example!

"I have no idea where I'm going. But the real question is, what was I doing here in the first place?" -- Art Buchwald

This is a bit of a pet peeve of mine, and ordinarily I wouldn't even bother to write about it except for the fact that I saw this article on MSDN and just had to shake my head in quasi-disbelief.

An otherwise excellent article on how to do BHO's (Browser Helper Objects) in managed code, and what does their example do? You guessed it: a "Hello World" MessageBox in your Browser! Good God, folks! Is that the most innovative code illustration you can come up with? It's completely USELESS! How about getting an RSS feed, doing a search, or creating a link?

You see something similar in many code examples, both in books, and in print and online articles. All you get is a Console application that "illustrates" a technique that should have been put into a self-contained class library. Instead, all the "guts" is totally tied up into the Console app -- often making it extremely difficult, especially for n00bs, to do something useful with it.

Naturally, its almost never that a real - world developer would ever want this code in a console app, but that's what you get.

Oh, I understand the rationalization that many users don't have Visual Studio and maybe they are doing their development in Notepad and using the command line compilers. Total B.S.! Visual Express products are all free now, and SharpDevelop, an open source IDE that rocks, is also free. So, that "explanation" doesn't cut it with me.

I really think writers should give serious thought about the usefulness of the code examples they publish. I almost always try to illustrate a technique by providing a full example with a class library, and where appropriate, an ASP.NET Web Solution or a Windows Application to go with it that uses same. It only takes a little bit more time, but I am sure that the end-users appreciate it. And ain't that what it's all about - the end user?