Recently, Mike posted his experiences relying on intellisense instead of documentation while working with the new Whidbey Mail APIs. I am one of those (assuming there is such a camp) who believe a class browser and/or intellisense should suffice for understanding an API without requiring topic after topic of reference documentation. Sure, I am exaggerating a bit. I think conceptual documentation is far more important so it can help explaining whats there, why it is there, and how it can be used. The idea is that consistent naming (all public names: type names, properties, methods, events, and yes, parameters as well) combined with standard design patterns go a long way in helping preserve the flow of thought while programming, without requiring a context switch into the documentation viewer.
Resources such as the design guidelines, and Brad's Designing .NET Class Libraries series go a long way in documenting and establishing these conventions and designs. Go through them, and then be sure to keep a copy of the reference handy.
The .NET framework is (generally speaking) more consistent than things like Win32, COM and script APIs. Sure there are exceptions and some relatively harder and more involved APIs, and you can tell them apart as soon as you find the need to reach for F1, or the need to browse to your favorite search engine. Alas, I have my own share in contributing badly named APIs... one that is fresh in memory from a recent discussion with folks here is the "ExtractTemplateRows" property on DataList from v1. I am sure there are others APIs... :-).
So here is a quiz for you guys: what does this funky sounding property do?
Posted on Friday, 8/12/2005 @ 4:34 PM
| #
ASP.NET