Simple Guidelines for Building Reusable .Net Libraries

Wed, 21 Nov 2007 12:51:28 GMT

There are some great (and very thorough) documents out there that can give you fantastic guidance on creating beautiful, reusable .Net libraries, Krzysztof Cwalina's Blog is my personal favourite. Most of it, however, is pretty verbose, very long and just feels a lot like overkill, so here are a few things I've done in the past that seem to work.

The 80/20 Split
Consider the core functionality that 80% of the library users want to achieve, stick all the classes you need to achieve a solution in that 80% region in a concisely named namespace. Generally this means asking yourself: What do people want to do? and What can I give them to help them do that?
Next, consider that final 20%: Can your library be extended? If so how? What are the unusual, complex scenarios that require a deeper understanding of the technologies involved to build a solution? Once you figure this out, create a child namespace of your '80%' one and expose only the public types required to achieve that final 20%.
Visibility Modifiers are Your Friend
(Generally) No one cares about your implementation details - if they do care its usually because your public interface sucks. In summary, if its not vitally important to getting the job done, hide it. Use internal for those important classes that ship data around your library but never see the outside world, mark static holder types as static, and remove the constructors for types that are constructed by a factory. Use 'internal' as the default modifier for type visibility and before changing it to public spend a few minutes thinking:
1. Does the name of the class really say what it does? (Nobody reads the manual)
2. Do the constructor arguments convey the minimum information needed to create a 'sane' instance?
3. Is this class useful to a user? what would they do with it? where would it come from and how is it consumed?
Encapsulation is Your Best Friend
The user of your library didn't read the manual, they'll probably ignore the intellisense summaries too. Design your class so that everything you can do, you should do.
1. Public fields are evil (and inexcusable), use properties instead
2. (Generally) There is no need to expose a setter on a collection property, so don't do it
3. Wherever it makes sense, use immutability by marking fields as readonly

More later...

--W

Will's space: .Net Guidelines

Simple Guidelines for Building Reusable .Net Libraries