Thursday, May 17, 2007

Pet Peeve: Examples that do nothing but demonstrate the syntax

I hate documentation that does nothing but repeat verbatim what can already easily be deduced from the syntax. I mean, how often have I see a property called "Foo" with the description "Gets or sets the value of Foo.". This is plainly idiotic. This documentation won't help me at all if I don't know what "Foo" is used for, what values it admits, and whether there's lots of it on the moon.

So can't Microsoft's writers do better than this example?

From: System.Configuration.SectionInformation.ProtectionProvider

The following example shows how to get the ProtectSection value of a ConfigurationSection object.


static public void GetProtectionProvider()
    SectionInformation sInfo =

    ProtectedConfigurationProvider pp = 
    if (pp == null)
        Console.WriteLine("Protection provider is null");
        Console.WriteLine("Protection provider: {0}", 

Thank you very much. Your attention to detail in providing me with 100% example coverage in the documentation has been most enlightening. Fortunately I was just casually browsing through the Configuration API so I don't actually care about the ProtectionProvider property. In any case, I'm pretty sure I could figure out what to do with it. And if in doubt, I can always whip out Reflector. That's an especially useful trick with such programmer-friendly management-approved frameworks as ASP.Net.

P.S. Microsoft is by no means the only offender here!

No comments: