Keith Watanabe * NET 2.0

I saw this video link presentation that was very thought provoking (and long).  the main thing that I got out of it was the message that APIs need to be simple.  I've been working (and cursing) a lot with Java lately and my big complaint is the amount of boilerplate code that I have to write.  Also, I've been noticing how things like Spring and Hibernate which are supposedly making one's life easier actually end up complicating one's system just as equally.  The primary problem I see with it is the sheer complexity involved.

The video linked below emphasizes simplicity.  Programming  and interfaces are all about APIs.  I like to use  what I call the "Eddie Van Halen Theory of Guitar Pedals."  Eddie Van Halen used to go down to his local music shop to find the next latest and greatest gadget.  The owner would attempt to pawn off something sophisticated with an incredible number of options.  The editor article asked him, "So do these give you too much control?"  Eddie's reply was, "No, they they don't provide any control!"  He goes on to demonstrate how things like his guitar only has one knob.  Why is this important?

This is linked to Apple's success and why Linux hasn't quite taken off as home operating system.  The formula is this: keep things simple.

The less number of arguments in your API, the less options being handed out, and the more that the actual implementation can handle are the keys for developing successful APIs.  Make things behind the scenes do all the work and keep it invisible from people.  I've seen for instance Japanese coding.  It's horrible.  However, when I use a Japanese keitai or drive my Toyota around, I never say a thing.  That tells me that the insides of these devices are probably equally complex and horrid, but the bundling forces me not to care about those details.

Part of how I design APIs involves having the object absorb information through numerous setters and then calling a process method which takes all the setters and does something magical on the backend.  People don't need to know what process() does, they just need to know the outcome and expected outcome based on the various attributes set on the object.

Likewise, I tend to  limit the number of parameters and return values being sent back.  You should set up some arbitrary rule where the number of parameters should not exceed 2-3 and limit the checked exceptions on your signatures (that is, if your language supports this feature).  If you need more values to be passed in, consider using an object with various attributes as options or maybe an associative array/hash.  In those cases, an object is great if you have a limited number of attributes, whereas an associative array works best if the number of attributes start overflowing.  For instance, at work I have this horrible form object that probably has around 40-50 attributes.  The thing that drives me crazy is that there's no easy way to avoid the set/get dilemma (which is really more of a problem with the way the damn forms and page flow was designed rather than an application issue).

The other reason why this is important is that probably you want to hide how things work for people.  It's psychological.  If a killer developer, for example, saw 30 select statements being regenerated in the code, there's an automatic temptation to 1) avoid using the API; 2) attempt to optimize and break the code himself.  But if the developer was under the assumption that the code just would work out of the box, he wouldn't spend the time normally attempting to fix it and focus on how he could use it to solve his more immediate problem.

Lastly, design APIs for usage, not performance.  APIs are best thought of in terms of interfaces.  Some languages don't support it or don't support it well.  However, if you change your attitude to force people into thinking in terms of usage rather than optimization, part of your headaches will be relieved.  Why?  You're more worried about how people will use it and if it even has an audience.  No one likes an overcomplicated thing that they must employ.  EJBs for instance were cumbersome and imo failed except as a marketing ploy by Sun.  People like and need simplicity.  So aim at that rather than going for performance.