Designing Programming Interfaces

I don't think I'm going to use twitter anytime soon myself, but from time to time I am clicking through some linked tweets, and some days ago I came across this line:

why is it that good APIs are harder to write than good code?

(via Steve's OGRE Dev Tweets). That's soo right. Basically, you have to design the interfaces, think about them, rework everything, test them yourself and do this all over again. That is, if you really want to have some simple-to-use but still powerful, generic and extensible interfaces. Currently I'm doing this with the Actionscript 3 interface for CopperCube, but I think after now some iterations I have found a nice solution.

six comments, already:

The answer seems obvious to me: You need to define the requirements yourself, and you have to guess at how people will use the library. Neither task is very easy! An iterative approach is probably best.
Michael - 08 04 09 - 23:55

I think the main point is that there is always something you forgot in first place that is hard to integrate later … maybe not hard to integrate but then you realize that this part would break your nice interface, so it’s better to do a redesign.
Brainsaw (link) - 09 04 09 - 07:31

Just like Michael said, iterations! Together with community feedback that can’t go wrong. Good luck anyway. I myself just started to try out Irrlicht after feeling Ogre didn’t satisfy my needs. Hope this goes well :)
Flawe (link) - 09 04 09 - 14:47

Glad it resonated with you :)

And about iteration – actually the whole point is that iterations are more difficult. The typical approach to code quality is to write, review, and revise/refactor, but when you’ve published a public API that other people are dependent on, a laisse-faire design philosophy is not longer desirable, because every breaking change is potentially a huge pain for your users. It means that you need to put a lot more effort into up-front research and design. Of course you’ll still end up revising and refactoring anyway, but you need a far tighter hold on it than in the typical internal project.
Steve () (link) - 09 04 09 - 16:30

No matter how beautiful an interface, I always find several severe flaws when I try to use it for a practical purpose. It’s always good to have a full blown side project that uses the library being developed alongside the actual thing.
BlindSide - 11 04 09 - 02:38

Yes, It is difficult on users of public library, but still important changes should go in iteratively. Like Python 3 may look like burden but, actually it is becoming lot better and there is community tool for Python2to3.
kinjalkishor () - 16 04 09 - 18:22

Remember personal info?
Email (optional):
URL (optional):
Enter "layered" (antispam):
Comment:Emoticons / Textile

  ( Register your username / Log in )

Notify: Yes, send me email when someone replies.  

Small print: All html tags except <b> and <i> will be removed from your comment. You can make links by just typing the url or mail-address.
Note: If you type in your email adress above, it will be visible to other visitors, although it will be hidden for bots using javaScript.