How to build a great Framework
Developers get delirious with excitement when you give them the task to build a new SDK or a framework - they immediately think of building something that will rival any and all frameworks that have come before them and that it will be so flexible it will be able to do things you have yet to think of. Think I'm exaggerating... go ahead... ask one of your Developers and watch their eyes light up. So if the desire to write a framework is met with such unbridled enthusiasm and ambition - why do the implementations for a number of SDKs suck and what makes a good framework? It really isn't complicated when you think about what you need to do.
Imagine you are the Consumer
When I start writing a framework that other developers are going to consume, the first thing I start writing is some pseudo code (a great combo of C#, JavaScript, maybe some XML or SQL, whatever) that I use to define the interface of how users will use the API. The goal here is to make accessing your work as efficient and logical as possible. I.e., do I really need 12 overloads on that 1 method? Will someone be able to connect the dots between initializing this member before calling this function to fire this event? If you can't logically walk the steps than how do you expect your users to? There is a great book out there called Framework Design Guidelines - it's all about some of the people that wrote the .NET framework - what they did right, what they did wrong. The book is 4 years old now, but it is such a great reference for accomplishing this sort of task. My favourite part is hearing from the guys who designed the System.IO namespace - when they put it in front of some skilled developers no one could figure out how to use it. It's an incredibly powerful namespace with much more functionality then its predecessors but the usability fell flat when put in front of its core audience.
Meaningful Responses
Alright - so you've got an API that's great to work with, users are getting it and then they hit an exception or error of some sort and what they get back is completely meaningless garbage that gives them no guidance as what they should try next. I love using "mature" .NET Interop wrappers that are specifically built to wrap around the complexity of COM components to make it easier for you to use only to give you some error that gives you an HRESULT to go with. What they couldn't intercept the message and write some code around what was going on internally? If you are lucky someone on the internet has encountered the same issue, if you are really, really lucky - that person has figured out what the error means, otherwise you're on your own to start down the road of trying to figure out what this error alludes to. I use COM Interop as an example, but there are many other examples - just the other night I was using the .NET Entity Framework against SQLCE4 and kept getting some "cannot open db" error. When I drilled down 6 levels in the inheritance chain I finally found that the error was in the password of my connection string. If this had of been bubbled up to the top of the stack I could have blissfully moved on (and saved myself some time). The point here is, you know why exceptions and failures are happening, so take the time to craft some informative messages to your user: Error - Impact - Suggestion. In the case of my EntityFramework example; "Cannot connect to the database, data will not be loaded, check your datasource or password in your connectionstring". Wordy? Maybe. Useful? Hell yeah.
Document thy Work
I don't want to read a 400 page novel on how to use your API - sometimes I do, but not 85% of the time. I just want to get up and running ASAP. .NET gives you the most simplistic tools to write comments - /// - that's it, type those 3 characters over any method, class, etc and it will give you the structure to work within. But do you do it? Really do you? But how much do you depend on it to help you in your daily programming? Recently I was working with this API that applies some metadata to files - it had NO documentation and NO comments. To top it all off it had great method signatures like GET, SET, DUMP, PEEK. A lot of my time was spent trying to determine which methods I should use in my task but had to aimlessly try different implementations. Something like - GET - Opens the file exclusively to access metadata, PEEK - Accesses the file's metadata without creating an exclusive lock - would have helped immensely. If you are writing external documents that your users need to read, add a reference to it in your code - what harm does that do? Here's a secret, beyond it's self-explanatory name, no one reads the "README" file until after they have hit an error, no one. So putting a comment into your code that says - "If you are trying to do this and are encountering errors, see the ReadMe file" is not going to ruin your framework.
Test Coverage
Over the last few weeks of 2011 I've been evaluating some logging frameworks for some applications that I have been working on. (I'll blog about my favourite one in my next post). When I installed some of these frameworks, I saw they had Unit Tests - great I thought, let's run these badboys and see what this baby can do. I was blown away when some where broken and didn't run. Here I was spending time validating unit tests when I wanted to be coding MY application. If the Unit Tests are broken, surely I must have done something wrong right? Not necessarily, in some cases there were some errors in the code - either through knowledge of known issues or lack of additional frameworks. If you are going to validate your framework against Unit Tests (YES PLEASE DO) then the onus is on you to make sure these things are rock solid against each and every release. If they are not and you make the call to not fix them (that's cool) do your users a favour and yank them. No harm no foul, I see no Unit Tests, I'm not going to try and run them (heck I won't even know they were broken). The last thing you want to do is give a guy a reason to not even look at your framework because your test suite broke before they even started writing code.
So here's the thing - developers can be lazy (not all, but we are a strong and proud number) and by having a simple API, with straightforward documentation with enhanced and useful response codes/messages that is well-tested and provides (PLEASE) a valid Unit Testing project you will be well on your way to getting your framework adopted by your developer community and getting the word out on what a great framework it is. Think of the last framework, third-party API, whatever you used - when it went great what was the first thing you said - "It was easy with component ABC" - that's what you want to happen, that's your end goal, always.