Namespaces and const
Andor Salga | 12 November, 2008 | 17:41
As our library expands with more functions, classes and global variables, the need for namespacing increases. I started placing code in a C3DL namespace when I wrote the matrix stack operations. However, yesterday I was looking in the constants.js file and saw the ‘tolerance’ variable. It’s a const variable used when comparing floats to check if they are close enough to be considered equal. Tolerance is global which allows us to easily use it wherever necessary. However, it is likely that users will have their own variable named ‘tolerance’, so it makes sense to just pack our tolerance into the C3DL namespace. This is where the problem started. I couldn’t find the syntax to properly create a const within a namespace. Hopefully I’m wrong and there is a way to do this, but from what it looks like I’m left with few alternatives.
I could remove the constness from the variable and then I would be able to place it in the C3DL namespace. It would be up to us to make sure our library does not assign new values to variables which should stay constant such as ‘tolerance’, ‘far_clipping_plane’, ‘near_clipping_plane’, etc. Although if users start using our globals for their own needs, they may assume we made sure it is const and users can end up accidentally overriding it, possibly creating bugs.
We could also just ditch the javascript ‘namespacing’ idea and place C3DL_ in front of everything. That way our variables can stay constant and be unique. The problem I have with this is that if used with functions, C3DL_popMatrix() is just too awkward.
Last idea I have is to use a hybrid naming system: place all our functions in the C3DL namespace but prepend symbolic constants with C3DL_. This will allow us to keep the variables constant and unique by name as well as keep the functions unique by namespace. The only problem I have with this is there is a slight inconsistency, but will users mind? If we decide to use this method, our function calls will look something like C3DL.popMatrix() and constants would be C3DL_TOLERANCE. I’m open to suggestions on other ways to fix this issue.
I could remove the constness from the variable and then I would be able to place it in the C3DL namespace. It would be up to us to make sure our library does not assign new values to variables which should stay constant such as ‘tolerance’, ‘far_clipping_plane’, ‘near_clipping_plane’, etc. Although if users start using our globals for their own needs, they may assume we made sure it is const and users can end up accidentally overriding it, possibly creating bugs.
We could also just ditch the javascript ‘namespacing’ idea and place C3DL_ in front of everything. That way our variables can stay constant and be unique. The problem I have with this is that if used with functions, C3DL_popMatrix() is just too awkward.
Last idea I have is to use a hybrid naming system: place all our functions in the C3DL namespace but prepend symbolic constants with C3DL_. This will allow us to keep the variables constant and unique by name as well as keep the functions unique by namespace. The only problem I have with this is there is a slight inconsistency, but will users mind? If we decide to use this method, our function calls will look something like C3DL.popMatrix() and constants would be C3DL_TOLERANCE. I’m open to suggestions on other ways to fix this issue.
For name spaces, my suggestions would be: Use c3dl as the
Jeremy Giberson | 13 November, 2008 | 20:18For name spaces, my suggestions would be:
Use c3dl as the name space, not C3DL. The reasoning being that its faster to type with out worry for caps lock or shift key usage. And its going to be typed a lot when coding.
var c3dl = {};For constants, just for symbolic reference of them being constant, I would place them under const in the name space.
// etc. capitalization can be all uppers if desired but I would stick with camel cased for multiwords
c3dl.const = {};
c3dl.const.tolerance = 0.0001;
c3dl.const.version = 1.0;
c3dl.const.farPlane = 300.0;
c3dl.const.nearPlane = 100.0;
Move all objects into c3dl, and helper functions into c3dl grouped under an appropriate name space.
var c3dl.model = function() { /* model stuff */ };
var c3dl.vector = { };
c3dl.vector.make = function (x,y,z) { };
c3dl.vector.cross = function (v1, v2) { };
// so on, and so forth
Notice the difference in the way model and vector were defined. model is a function definition because the intention is to use it as object factory. However vector is a grouping of related functions. The reason why vector should be a utility class is to standardize naming conventions for the vector functions. Right now, there are functions named with vector being the first word, vector being the last word and even vector being a middle and last word. Naming schemes should be consistent. Secondly, since you have an actually grouping object you can then generate shortcuts to the utility functions by creating a new variable and assigning to the helper class. So it actually lends to less typing & more clarity.
IE:
// using c3dl classes/functions
var m = new c3dl.model(/* params */);
var resultVector = c3dl.vector.cross(vec1, vec2);
// using shortcuts to make typing less burdensome
var v = c3dl.vector;
// lots of vector work follows
v.add(vec1, v.scale(v2, v.make(0.5, 0.25, 0.75));
// which was much easier to read since 3 function calls could drop the c3dl.vector prefix's.