API Design

With regards to a common interface, one of the things which I made sure was that all managers which relay data to the game code use a standard subscriber interface. E.g., Input, Game Messages, Input Actions, Etc. all use HandleXXXXX(const xxxx& event) methods for callbacks. In addition, to subscribe to a message you invoke XXXXAttach(eventType, ....). And to unsubscribe you invoke XXXXDetach(eventType,...). Note that all those functions are declared in interfaces specific to the manager. E.g. IActionListener, IKeyListener, IMessageListener.

Another point is to follow "Resource acquisition is initialization" as much as possible. So anything which requires "open" and then "close" should be wrapped in an object which opens in the constructor and closes in its destructor.

Intrusive reference counted smart pointers are also a great feature to use with Factories for creating objects, like you mentioned in your post.

- Jason Citron
- Team nine:14, System Architect
- www.nine14.net
--------------------------------------------------
Checkout the prototype of Fates Forgiven at www.fatesforgiven.com

While it may be tempting to go hog wild and throw in every design pattern you can find, I'd caution against this fact. Decide upon a high-level API beforehand that you will adhere to. Having a vision for the project (from an architectural standpoint) will give you scalability. One example of a high-level API is that of a publish/subscribe model like Clash mentioned. You'll most likely use a few patterns in your design, even if it isn't the exact implementation from GoF. What is important is the idea, not the implementation.

Then, when you decide upon that, begin implementing objects as they occur. Pay special attention to method names - using a standard vocabulary will make your API easier to learn. For example, if your objects all have a unique identifier, but don't have a common base class, then make the member function be the same across all of them, such as GetID(). After a certain amount of time you will spot sections of code that are repeated across modules, which should suggest refactoring to you. Move those up into the objects if need be, or consolidate them into a utility library. If you run into a situation that puzzles you, then step back and see if a pattern would help, such as the need for a factory. (Of course, if you know up-front that you need to make objects based upon runtime conditions, then you'll need a factory. Just don't spew patterns everywhere in the code just for their own sake. I see a lot of people on this board do this for no apparent reason.)

In my experience, persistence is far more useful than any sort of 'talent.' Pretty much the only way I can see is to learn, and the only way to learn is make mistakes. My current project (touch over 10,000 lines of code) I went through at least fifteen design iterations - and I knew exactly what sort of high level API I wanted, I simply tuned it until I was happy with it.

Don't pull out the big guns until you have big problems. :)

Definitely browse through docs for the big API's out there to see how things are being done now. The Java API's are pretty good from a design standpoint. Pick a naming convention and stick with it. And like antareus said, design before you begin, Having everything mapped out will save you many a headache. Good luck.

Another thing you might want to consider that I have found usefull. Is that you won't get it completely the way you want it your first time through coding it. I will echo what has been said already designing first before you start coding is a must and you should do that. But sometimes depending on the project you can over design yourself into a nightmare. So I would suggest that you develop things in steps. Create a design doc that both shows the features you want to implement with your api (start small and build) use uml diagrams to show how your features will be implemented for developers use. I would iron out the essentials for what your api will accomplish start with the unique features such as those that single yours out from the rest.

After you have a design and a pretty clear idea of what you want to initially write then code it, debug it, test it, and if you like it build more features into it. If you don't like the way it turned out or you found that your design was inadequate well you'll have to start from scratch.

On my current project I have redesigned it once already because I had not anticipated some of the design problems. I know now that I could not have designed the system any different the first time because it's my first or the type of program I am developing.

Documentation should sometimes be treated like code except you don't need to (document your documentation) there are actually books and srs's and other types of documentation which have specific documentation on how to read them. Which I think is crazy. If you know how to read you should be able to have a completely understanding of the system from your documentation.