Designing Quality Frameworks

A few tips...

1. The most important thing to remember when designing APIs and frameworks is that you must know your subject area. Deep within the heart of every developer lurks the temptation to just “start coding” and “let it come to you.” While highly skilled developers may still end up with a working framework, very few developers can create a usable framework this way. Dealing with the grey areas inside your class hierarchies will be time consuming enough when you know your subject matter. Do not allow yourself to become a lazy programmer, or the sleepless nights that come weeks or months later will quickly give you a reason to be lazy.
   
2. The second most important thing to remember is that the people who will be using your framework do not have anywhere near the knowledge of its internals that you do. As a result, you must:
1. Keep it simple: Prefer strong typing to DataTables and generic collections. Prefer method overloads to lots of methods with slightly different names. Prefer multiple classes to gigantic classes. Introduce “convenience methods” into your classes (methods that perform simple conversions or call groups of other methods). Do not be afraid to introduce coupling between related classes, but make sure that you do it sparingly. If you find yourself constantly forgetting where certain methods are located or passing invalid values to other methods, chances are you need to rethink your architecture (after all, if you can’t use your own code with ease, I guarantee your customers will experience major frustration).
2. Validate inputs: Many times, users will just hack their way through a project, using only auto-complete as their documentation. As a result, they may pass invalid values without knowing any better. Do your best to ensure that this won’t cause strange things to happen.
3. Give descriptive error messages: There is nothing more frustrating that receiving a null reference exception from within a method and having no idea why it is failing.
4. Assume complete ignorance: Every day, hundreds of ignorant CS students are in training at your local university. Every day, thousands of ignorant developers buy software components. Eventually, some of these guys will buy your products.
   
3. The third most important thing to remember is that until your product ships, it is never too late to refactor public classes and interfaces. After your product is complete, take a good chunk of time to ensure that your framework’s naming conventions and processes are consistent and that everything makes sense. This is especially important for projects with large numbers of developers, but this simply practice can also immensely improve the architecture of one or two man projects. Keep in mind that once the product has shipped, even something as trivial as changing method names is generally out of the question. Taking 5 minutes to change that method name before the product ships will definitely pay off.
   
4. The fourth most important thing to remember is: Test, Test, Test. Unit tests are a great start, but they are only a start. Quality frameworks have many attributes, such usability which cannot be measured by NUnit. As your framework nears completion, take some time out and use it. Not only will this help uncover design flaws and provide extra test coverage, but you should also have some solid examples of best practices to show your customers by the time you are ready to ship.
   
5. The last thing to remember is: be consistent! Consistency comes on multiple levels:
1. With “the” framework: It is extremely important that you are consistent with the frameworks on top of which your product is built (such as the .NET framework class libraries). The more consistent you are with those frameworks, the easier the transition to your framework will be to your users. This simple principle is one of the easiest to obey, but is violated time and time again by component vendors.
2. With “your” framework: Equally important is that you are consistent within the walls of your own framework. Users will quickly become frustrated or confused if every time they open up a new namespace, everything functions differently.
3. With “their” framework: If there are general design practices in your industry, do not ignore them. Chances are that they are there for a reason.