A post on DanF’s weblog (via Scoble) reminded me of the thing I despise most about the MSDN: Samples for language reference.

I’m glad that the person who sat down and wrote the documentation took the time to write a short sample showing how to use the language element (thank you; I try to do that too in my own line of work), but some of the samples lack in several departments, such as actually explaining what they do and why.
I do not want to open a new instance of Visual Studio.NET 2003 (yes, I do know about Snippet Compiler, which is quite helpful, but I don’t use it), every time I browse for documentation. Not to mention the Windows Forms samples that, at times, require you to actually build a form with the ‘helpful’ “this sample assumes you have, on your form, a TextBox names Bernard, a GroupBox named Zachary and a full implementation of the Towers of Hanoi puzzle” comments at the beginning.
Even the simplest of examples don’t show an output at times (exempli gratia)… Quite ridiculous, and I assume you would agree.

Another thing one might consider is that the good people over at Microsoft would consider formatting their code (all it takes is a simple Ctrl+A, Ctrl+K, Ctrl+F combination, mind you) or at least using their own naming conventions guidelines
The example escapes me, but once I even saw documentation for a method with the sample excluding the actual documented method itself.



2 thoughts on “Console.WriteLine(1+1);

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s