What naming convention for a C API

Question

We are working on a game engine written in C and currently we are using the following naming conventions.

ABClass object;
ABClassMethod(object, args)

AB Being our prefix.

Our API, even if working on objects, does not have inheritance, polymorphism or anything. All we have is data types and methods working on them.

Our Constants are named alike: AB_ConstantName and Preprocessor macros are named like AB_API_BEGIN. We don't use function like macros.

I was wondering how this was fitting as a C API. Also, you may note that the entire API is wrapper into lua, and you can either use the API from C or lua. Most of the time the engine will be used from lua.

Answer 1

Whatever the API you'll come out with, for your users' mental sanity (and for yours), ensure that it's consistent throughout the code.

Consistency, to me, includes three things:

1. Naming. Case and use of the underscore should be regulated. For example: ABClass() is a "public" symbol while AB_Class() is not (in the sense that it might be visible (for whatever reason) to other modules but it's reserved for internal use.
   If you have "ABClass()", you should never have "abOtherClass()" or "AbYet_anotherClass()"

2. Nouns and verbs. If something is called "point" it must always be "point" and not "pnt" or "p" or similar.
   Standard C library, for example, has both putc() and putchar() (yes, they are different but the name doesn't tell which one writes on stdout). Also verbs should be consistent: avoid having "CreateNewPoint()", "BuildCircle()" and "NewSquareMake()" at the same time!

3. Argument position. If a set of related function takes similar arguments (e.g. a string or a file) ensure they have the same position. Again the C standard library do a poor job with fwrite() and fprintf(): one has the file as the last argument, the other as the first one.

The rest is much up to your taste and any other constraint you might have.

For example, you mentioned you're using Lua: Following a convention that is similar to the Lua one could be a plus if programmers have to be exposed to both API at the same time.

Answer 2

This seems standard enough. OpenGL did it with a gl prefix, so you can't be that far off. :)

Answer 3

There is a lot of C APIs. If you are creative enough to invent a new one, there's no "majority" to blame you. On the other hand, no matter which way you go there are enough zealots of other standards to get mad at you.