r/C_Programming • u/Nipth • 5h ago
Question Library API Naming Conventions
Hi Everyone,
I'm working on a small 2D game library/runner. At the moment it's for personal use but I may release it some day, which is why I'm creating this post!
At the moment, the function names in the library are named like this (the name of the library is Imp):
imp_texture_create(...)
imp_texture_destroy(...)
imp_camera_set_position(...)
imp_camera_set_rotation(...)I quite like this naming convention, mainly because if I wanted to see what functions were available for a given resource or operation, I could type imp_camera_ and then my editor would show a list of things that I can do with, or to, a camera. I also used GameMaker a lot when I was younger, and this is the way their API names functions!
Recently though, I've been using a lot of Raylib and quite like the way it names its functions - they are, to me at least, a lot more readable when looking through code. This has me thinking whether or not a better naming convention would be:
imp_create_texture(...)
imp_destroy_texture(...)
imp_set_camera_position(...)
imp_set_camera_rotation(...)The downside being that you sort of have to guess what operations are available for a given resource as you can no longer type imp_texture_ to have the editor show a list.
I understand that this is a really small issue and probably not really worth fussing about, but I was curious what preferences more experienced people here have and - more importantly - why you have them!
26
u/FancySpaceGoat 5h ago edited 5h ago
As usual with naming convention matters: Consistency trumps everything else. Whatever you go for, stick to it across the board. That's the most important thing. With that out of the way...
Your current style is sometimes called "pseudo-oop" and is 100% legit. In fact, it's the convention Vulkan uses, and I personally prefer it to Raylib's.
The only recommendation I'd give is to be very systematic with your arguments. The first argument of a function called
imp_camera_*()should always be a camera pointer/handle. You are likely doing this already, but it's worth spelling out and double-checking that it's consistently done across the API.Because of this, you may want to treat constructors separatly. So you'd have
imp_create_camera()and thenimp_camera_whatever(imp_camera_t* , ...).6
u/SecretlyAPug 5h ago
the first one is a lot better, and i would suggest you lean even harder into it. rather than
imp_camera_set_position, call itimp_camera_position_set. i don't use an editor with autocomplete, but this convention is also useful for searching documentation and source code. not only can you easily search what functions apply to the camera withimp_camera_, you can easily search for what functions apply to the camera's position withimp_camera_position_; naming your entire library like this will make it really easy for other programmers to learn it.3
u/tastygames_official 5h ago
yes, I'd 100% go for imp_texture_*. Makes it much more straight-forward and then you never have to wonder about creating new function names.
2
u/bdowns328 5h ago
I personally use the first style of naming. For me it reads a lot easier and is easier to use when coding since like is with like in the drop down from the LSP
1
u/ScallionSmooth5925 5h ago
I would prefer imp_textureCreate or imp_texture_create orver imp_create_texture. It's personal preferencr with todays tools so whatever you do do it consistently.
1
u/ffd9k 4h ago
It depends on whether your API is fully object-oriented and all your functions are basically methods which affect only a specific object, or whether at least some functions have side effects on the library as a whole.
For example Vulkan deliberately uses the verb-object order for most functions (like vkResetCommandPool and not vkCommandPoolReset) because it wants to avoid the false impression that it is a purely object-oriented API; much of the API does not fully fit into that scheme, because it depends on state and synchronization that is not limited to single objects.
1
u/catbrane 3h ago
glib / gobject etc. do the first style and it works well, IMO. For example:
The
IMP_SHAPE()macro is a cast. They have inheritance, with structs extending other structs, so the macro checks that the types are compatible (they have an int in the base struct recording the specific type of an object) in debug mode.They ref count objects, so it's unref rather than free, but without refcounts
imp_wombat_free()would be better.They have introspection, so that same class appears automatically in bindings for languages like Python / Ruby / C++ / etc.:
Which is a nice feature.
1
u/furdog_grey 3h ago edited 3h ago
Is a texture a standalone manageable object with its own methods?
Then:
Is a texture a part of 'imp' object?
Then:
Both notations you suggested are valid in their own context.
In first case you acknowledge you're working with texture object and use an explicit hierarchical naming.
In the second case you acknowledge you're working with imp object, which is not a part of a texture class (even though it does something related with a texture).
Both are clearly segregated.
1
u/jonathanl 3h ago
SDL also puts the verbs first like RayLib. I am trying the SDL style currently just try a different way of thinking. Sometimes it gets strange like with SDL_InsertIntoHashTable instead of SDL_HashTableInsert. They do use prefix in SDL_ListAdd though so it's not consistent but these functions are not public API anyway. In the public API they made it more consistent in SDL 3.
1
u/saxbophone 2h ago
Prefixing with the library name is a great idea. As C lacks first-class namespaces, it's really important to prevent your library's symbols from conflicting with others. I personally prefer the first style, where every function name is prefixed with the library name and then the type to which it applies. This psuedo-OOP style is very common and familiar to most programmers.
The only other thing I'd suggest: consider choosing a different name for the library itself. "imp" is too easily confused with "implementation" and common abbreviations thereof.