While I'm still connecting A to B in experimental ULib v3 code, I realize there's a need to set standards on style and how to handle cases. I'll keep posting my ideas here as they occur to me. Feel free to argue on any point. I'm open to any suggestions. Some of these will be pretty basic while others will be very specific. These are as much for me as anyone else.
* Never use garry-specific operators '!', "!=", "//", "/* ... */". Avoid the garry-bit shift operators "<<", ">>", "~" if at all possible. I've already made the argument for this so we'll leave it at that.
* Variable names have no capitals and use '_' for separation. Should be as descriptive as possible.
Be descriptive with for loop variables too. I'm infamous for using "for k, v in pairs( blah ) do", which is awful unless the loop consists of <5 lines.
* Function names user lower CamelCase (begin with lower-case). I think this will help give distinction between variables and functions... Lemme know what you think.
* If you're using a pseudo-class, the class name should use upper CamelCase (begin with cap). Again, I think this will offer distinction between variables, functions, and classes.
* Liberal usage of string.format(). This function is wonderful, really. If you find yourself doing a lot of concatenations, use string.format() instead.
* If you're doing a new feature, don't consider it complete until you've written both documentation and test cases for it. IE, don't close the issue on flyspray/mantis.
On this note, even test cases should be fairly well-documented. If I'm looking for example usage of code, test cases are always the first place I go.
* Documentation! Remember we use Natural Docs for our documentation, so write documentation in Natural Docs style (which is pretty much anything you want as long as you follow general rules). I'll try to set up a documentation auto-updater like we had for UPS on the old server again.
I want the documentation in a condition where we, as ULib/ULX devs, are using it while working on our projects. I almost got to this point with the current documentation but often had to refer to the source for specifics.
Include revision information in the documentation. What version was the function/class created in? What versions was it modified in and why?
* Lots of debug statements via our logging stuff. I'll write more about this once I have code showing how I'm using it...
* Unlike in previous ULibs where we included all files through a single initialization, I'm leaning more toward including files where they're needed this time around. Since this brings up the possibility of a file being included multiple times, include the following code at the top of each file... Lemme know if you despise this.
if FILENAME_LUA then return end -- Return if file already loaded
FILENAME_LUA = true
* Flags in the code! This makes for easy checks to make sure we're good for a release.
If you're committing something that needs work, put "-- TODO (general explanation)".
If you're applying a hack (IE, garry blocked something he shouldn't have and you're going around it), mark it with "-- HACK (explanation)".
If you add code that should be removed when you're done working on it, add "-- REMOVE (just the line? this function?)"
Anyone have more?
