Hi guys, to be totally honest X3D is my first ever C library (or library for that matter :P ). I'm just trying to figure out what a good naming convention will be for various things. For structures, I currently have all of my structures prefixed with "X3D_", followed by the name in Pascal Case e.g.
X3D_RenderContext.
First off, does this seem like a reasonable way to name structures? Second, I have several structures that represent the same idea, but with different types of member variables (my best analogy is a C++ template). For example, I have 3D vectors, some that need to hold int16's, int32's, or uint8's. My current convention is that I put the "subtype" after the structure name:
typedef struct {
int16 x, y, z;
} X3D_Vex3D_int16;
typedef struct {
int32 x, y, z;
} X3D_Vex3D_int32;
The problem is, I'm using int16 vectors all over the place and barely using the others, and it gets annoying to type out such a long name. Would it be confusing to have "X3D_Vex3D" be a shorthand for "X3D_Vex3D_int16", and if you need anything else then use the long name? That is,
typedef X3D_Vex3D_int16 X3D_Vex3D;
My next question is about function naming. Since C lacks classes and namespaces, I'm trying to figure out how to group related functions that operate on a common object together (almost like a class). For example, suppose I have functions that e.g. create a new 2D polygon, draw a 2D polygon, and find the geometric center of one. At first, I though I should name the methods in this format:
x3d_[struct type being operated on]_[name]
For example:
x3d_polygon2d_create()
x3d_polygon2d_draw()
x3d_polygon2d_center()
That way, it would be clear that all of these methods "operate" on an X3D_Polygon2D. As you can see, though, these names start to get long faaast. Suppose I want to have a function that normalizes an int32 vector. This becomes:
x3d_vex3d_int32_normalize()
I mean it's really clear what this is doing from the name, but will people be willing to type out something so long? Also, is the ordering ok? It could just as easily be
x3d_normalize_vex3d_int32()
x3d_create_polygon2d()
x3d_init_rendercontext()
So, I guess my main questions are:
- Should all of my structures/functions begin with the "X3D" prefix, or is this just unnecessarily increasing the number of keystrokes?
- Is my solution to "template" types reasonable? Can I have a "default" type like Vex3D_int16 for the most common case?
- Should I follow a strict, consistent naming convention for functions based on the type they're operating on?
- Which order seems better, "x3d_create_polygon2d" or "x3d_polygon2d_create"?
I should point out that 1) as many of these functions as possible are declared inline or static inline, and 2) I'm using Doxygen to generate documentation. I really appreciate any help you guys can give me because I'm driving myself crazy trying to figure out what convention to use. Thanks!
Prefixing all your function and type names is indeed the good thing to do (just like many other libraries like GL and SDL), so you won't have any name collision with other libraries. Otherwise, it's pretty much up to the author, as long it's well documented and the naming conventions are consistent through the entire library, well, that works. It's a good idea to check other similar libraries to check what are their conventions. For the types, I'd say "X3D_Vex3D16" would be a good compromise. And for the function names, I think you can overload functions, so you can have things like:
x3d_normalize(X3D_Vex3D16 vector);
x3d_normalize(X3D_Vex3D32 vector);
So you don't need to put the type in the function name. I don't remember well, but in C you can have different functions that have the same name, but different signatures.
Hope this helps.
Quote from: Juju on July 01, 2015, 11:55:13 PM
And for the function names, I think you can overload functions, so you can have things like:
x3d_normalize(X3D_Vex3D16 vector);
x3d_normalize(X3D_Vex3D32 vector);
So you don't need to put the type in the function name. I don't remember well, but in C you can have different functions that have the same name, but different signatures.
Hope this helps.
Unfortunately C doesn't have overloading (only C++ does) :( I guess I'll just play around with names and use my best judgement. Thanks guys!