* WalrusIRC

You need to have 5 posts and not be part of restricted usergroups in order to use the WalrusIRC embedded shoutbox. However, you can also access our IRC channel called #CodeWalrus via EFnet.

Author Topic: Naming Convention for a C Library (X3D)  (Read 892 times)

0 Members and 1 Guest are viewing this topic.

Offline catastropher

  • Full User
  • Safe-haven access
  • Join Date: Apr 2015
  • Location: US
  • Posts: 138
  • Post Rating Ratio: +12/-0
    • catastropher
  • Gender: Male
Naming Convention for a C Library (X3D)
« on: July 01, 2015, 10:40:28 pm »
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.
Code: [Select]
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:

Code: [Select]
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,
Code: [Select]
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:
Code: [Select]
x3d_[struct type being operated on]_[name]

For example:
Code: [Select]
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:
Code: [Select]
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
Code: [Select]
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!


  • Calculators owned: TI-83+, TI-83+ SE, TI-84+ SE, TI-Nspire CX, TI-92+, TI-89 Titanium
Creator of X3D, a 3D portal rendering game engine for Nspire, 68k, and PC

Offline Juju

  • aka Yuki Kagayaki aka J̵̭͕͇ù̞̭̝̯̦j̴̭̙̗͖͡ù͏͓̲̕
  • CodeWalrus Staff
  • Super User
  • Server Maintenance
  • Moderator
  • Forum Maintenance
  • Original 5
  • CodeWalrus Supporter
  • *
  • Join Date: Nov 2014
  • Location: Inside a walrus
  • Posts: 3017
  • Post Rating Ratio: +28/-2
  • Couch potato
    • jul.savard
    • juju2143
    • @juju2143
    • juju2143
    • @julosoft
    • juju-kun
    • /u/juju2143
    • juju2143
    • @juju2143
    • Juju's shed
  • Gender: Female
  • WalriiPoints: 99999
Re: Naming Convention for a C Library (X3D)
« Reply #1 on: July 01, 2015, 11:55:13 pm »
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:
Code: [Select]
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.
  • Calculators owned: TI-83+ (dead?), Casio Prizm (also dead???)
  • Consoles, mobile devices and vintage computers owned: A lot
On hiatus until when the sun goes dark in plain day. Won't have internet on Aug 22-23, so try to not kill each other during that time. SO POST LIKE CRAZY WHILE I'M NOT HERE THANKS
YUKI-CHAAAANNNN
In the beginning there was walrii. In the end there will be walrii. All hail our supreme leader :walrii: --Snektron

if you wanna throw money at me and/or CodeWalrus monthly it's here

Offline Duke "Tape" Eiyeron

  • Urist McEiyolobster
  • Super User
  • Join Date: Nov 2014
  • Location: (V)(-_(//));(V)
  • Posts: 1636
  • Post Rating Ratio: +11/-2
  • Fanciest Walrus of the oceans.
    • @@Eiyeron
    • Eiyeron
    • /u/Eiyeron
    • Eiyeron
    • Rétro-Actif : Rétro/Prog/Blog
  • Gender: Male
Re: Naming Convention for a C Library (X3D)
« Reply #2 on: July 02, 2015, 10:57:09 am »
NO you actually can't in C (or that would imply lots of linking hack)
  • Calculators owned: A lot.

Offline catastropher

  • Full User
  • Safe-haven access
  • Join Date: Apr 2015
  • Location: US
  • Posts: 138
  • Post Rating Ratio: +12/-0
    • catastropher
  • Gender: Male
Re: Naming Convention for a C Library (X3D)
« Reply #3 on: July 04, 2015, 11:36:00 pm »
And for the function names, I think you can overload functions, so you can have things like:
Code: [Select]
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!
  • Calculators owned: TI-83+, TI-83+ SE, TI-84+ SE, TI-Nspire CX, TI-92+, TI-89 Titanium
Creator of X3D, a 3D portal rendering game engine for Nspire, 68k, and PC

Offline Juju

  • aka Yuki Kagayaki aka J̵̭͕͇ù̞̭̝̯̦j̴̭̙̗͖͡ù͏͓̲̕
  • CodeWalrus Staff
  • Super User
  • Server Maintenance
  • Moderator
  • Forum Maintenance
  • Original 5
  • CodeWalrus Supporter
  • *
  • Join Date: Nov 2014
  • Location: Inside a walrus
  • Posts: 3017
  • Post Rating Ratio: +28/-2
  • Couch potato
    • jul.savard
    • juju2143
    • @juju2143
    • juju2143
    • @julosoft
    • juju-kun
    • /u/juju2143
    • juju2143
    • @juju2143
    • Juju's shed
  • Gender: Female
  • WalriiPoints: 99999
Re: Naming Convention for a C Library (X3D)
« Reply #4 on: July 05, 2015, 01:06:35 am »
Ah right, I wasn't sure.
  • Calculators owned: TI-83+ (dead?), Casio Prizm (also dead???)
  • Consoles, mobile devices and vintage computers owned: A lot
On hiatus until when the sun goes dark in plain day. Won't have internet on Aug 22-23, so try to not kill each other during that time. SO POST LIKE CRAZY WHILE I'M NOT HERE THANKS
YUKI-CHAAAANNNN
In the beginning there was walrii. In the end there will be walrii. All hail our supreme leader :walrii: --Snektron

if you wanna throw money at me and/or CodeWalrus monthly it's here

 


You can also use the following HTML or bulletin board code to share it on your page or forum signature!


Also do not forget to check our affiliates below.
Planet Casio TI-Planet Calc.news BroniesQC BosaikNet Velocity Games