Harold Serrano

View Original

Try to design user-friendly APIs

One of the goals of an API developer is to make the API user-friendly. Your public API should be compact and intuitive. It should provide enough information to start development without the need to read the whole manual.

The game engine is the first API that I have ever developed. As I used the API in several demos, I realized that the API's naming convention was not user-friendly. It didn't inform the user when and where to use certain functions. For example, the Collision Response of a character depends on its inertia tensor, center of mass, etc. These properties should be set in the initialization routine. So instead of using the "set" keyword as shown below:

void setInertiaTensor();
void setCenterOfMass();

I hint the user to use these functions in the initialization routine by prefixing it with the "init" keyword:

void initInertiaTensor();
void initCenterOfMass();

Also, the API did not indicate whether a function enables a behavior or property. For example, Collision Detection is a behavior that can be enabled, paused and resumed. In contrast, a character's name is a property that is set to a value. So instead of using the keywords "set" and "disable" as shown below:

void setCollision();
void disableCollision();

I hint the user that the function enables, pauses or resumes a characters' behavior. I also append the suffix "Behavior" to each function as shown below:

void enableCollsionBehavior();
void pauseCollisionBehavior();
void resumeCollisionBehavior();

In contrast, all properties use the prefix "set".

void setModelName();

A good API design is akin to a good GUI design. It should be simple enough for anyone to start using it and hard enough for anyone to use it incorrectly. Do not discount the importance of a well designed API. It is as important as writing documentation and as your (app) source code itself.

So make an effort to review, simplify and improve your public API.