The people who dreamed up the .NET API (most particularly the graphics APIs) and their documentation often make my mind boggle.
For instance, what would you think if someone said to you: “You have 5 different options. Four of these are exactly the same. The other one is sometimes the same and sometimes not (though we can’t say when or why), and you’re not allowed to choose it some of the time.”
That’s exactly what the official documentation for System.Drawing.Pen.Alignment states:
This property determines how the Pen draws closed curves and polygons. The PenAlignment enumeration specifies five values; however, only two values—Center and Inset—will change the appearance of a drawn line. Center is the default value for this property and specifies that the width of the pen is centered on the outline of the curve or polygon. A value of Inset for this property specifies that the width of the pen is inside the outline of the curve or polygon. The other three values, Right, Left, and Outset, will result in a pen that is centered.
A Pen that has its alignment set to Inset will yield unreliable results, sometimes drawing in the inset position and sometimes in the centered position. Also, an inset pen cannot be used to draw compound lines and cannot draw dashed lines with Triangle dash caps.
I’m not sure which is worse: documentation that explains the stupidity of an API, or documentation that doesn’t explain the API at all:
Gets a value indicating whether the control is mirrored.
Property Value: true if the control is mirrored; otherwise, false
(That’s all it says. There’s zero description of what “mirrored” actually means.)
These two examples are particularly bad, but the entire .NET API is filled with similar deficiencies in both documentation and design. Java’s standard libraries, while not perfect, are on the whole much, much better. If it weren’t too late already, the entire .NET team should be beaten over the head with a copy of Elliot Rusty Harold’s XOM Design Principles and then locked in a room until they cleaned up their mess. What they produced was simply amateurish.