As I wrote the other day, I was listening to Brad and Krzysztof talking about The Art of Building a Reusable Class Library. Most of this PDC pre-conf was pretty much common sense. What I like about it is that it is formalized common sense. You see, it turns out that your common sense isn't always compliant with what others consider common sense. From this session, and especially with a copy of their soon-to-be-released book, Framework Design Guidelines.
One of the early tips they provided was to group similar functionality by name. It may seem trivial, but I see it all the time that class library designers fail on this.
Let's say that you have a string management class for instance, in which yo would be able to append, overwrite, read and manipulate the text by regex. At a first glance, method names such as Append, OverWrite, Read and Manipulate may feel pretty good. But what would happen if you hade more, say 30, methods in this class. Wouldn't it be hard to identify that you can write by either appending or overwriting? According to these friends, it would be a better idea to group the methods by changing the names slightly, into something like Modify, Read, WriteAppend and WriteOver. This way you'll get all the writing methods nicely grouped together in your intellisence.
My one favorite statement from that entire day was the following:
Use abstract classes when possible - interfaces when necessary!
Using interfaces instead of abstract classes hinders the evolvement of your framework. Interfaces are awesome for defining strict contracts of your framework but is a real pain if you'd want to add generic features to a group of classes. There are two occasions where you might prefer interfaces over abstract classes:
1. When you want to create a hierarchy of value types
2. When you want to simulate multiple inheritance
At any other scenario, do favor defining classes over interfaces!
Fields vs. properties
Use properties. It is as simple as that. Even if you see no immininet reason to modify whatever value you'd want to expose, there might be a reason for it in v2. Have you considered that you might want to cache a value for performance reasons?
Documentation is important but it does not compensate for a bad API. What Brad said about that? "Good documentation on a bad API is like lipstick on a pig!" A bad API is a bad API. The solution is not to write fool proof documentation - the API in it self is what should be fool proof.
If in doubt - use the manual
If you are the slightest bit uncertain of how to implement something - have a look for something similar in your team's existing source code base. If you don't find it there, you might find a clue in the .NET Framework. Download and check out the Rotor code - it's pretty much exactly what makes up .NET.
Finally, The Pit of Success
Brad really focused on the importance of The Pit of Success - a definition that he has borrowed from Rico Mariani. As a framework- or class designer, you should design your deliverables so that someone using it would easily stumble into doing things right. The most intuitive route should not lead to failure or misuse of the framework. If you provide two options, the most preferrable should also be the one leading to the least work and the least risk of messing up the application that he's building.