Found an interesting post over on ISerializable – Roy Osherove’s Blog that outlines a few of the things that should be considered when designing software component interfaces. To re-summarize and add my own two cents worth here they are in my own order of importance.
- Resilience – (the best single-word description I can come up with) Your API must, by necessity, provide no details about its implementation. Without consideration of this objective it can prove difficult to re-tool when the time comes.
- Independence – You should generally avoid binding your API/interfaces to external components. Most especially avoid anything that determines the environment the code must run within (using System.Window.Forms, System.Web, System.Console etc). Of note this also applies while coding in addition to just interface design, avoid use of global assessors (i.e. System.Web.HttpContext.Current) provided by the aforementioned namespaces.
- Explicitness – we decided early on to be as explicit as possible about the API, so that the least guessing needs to take place by the user
Consistency – is the new API consistent with the other APIs that already exist, or does it go against the regular way things are done? - Discoverability – If a user knew they wanted to do thing X, would they know to use the API without help? simply from intellisense?
Single point of entry – everything should start from a single point (Isolate.Something()) - Readability – for the reader, not the writer (if you didn’t write the test would you find it easy to understand what it does?)
I’ve striken the following from my own consideration for the reasons stated:
Single way to achieve things – is there more than one way to do a task with the new API?
Not always a good thing, use your judgement and “keep it simple” will prevent this from being a problem.
Backwards compatibility – do we break an existing feature and cause some heartache for users?
See “Resilience” above, you already failed once be more careful next time.
Remember all of this basically helps to define the only phrase that matters:
“Keep it Simple”