Naming Conventions
elemnentals.js uses the following conventions for naming objects, properties, parameters, and variables.
- Objects
- In JavaScript technicanlly ALL functions are Objects, but inside elementals we use the distinction that any object you would call using "New" or would call the sub-properties of directly is named in CamelCase with a leading upper-case character.
- functions and variables
- Any function that would not be created as an object instance via 'new' and lacks sub-methods or properties, as well as any variables is entered in camelCase with a leading lower-case letter.
- CONSTANTS
- TECHNICALLY JavaScript doesn't have true constants but certain values stored inside elementals should be treated as inviolate. Any value stated in all upper-case should be left alone and under no circumstances should you try to change their values. They exist as handy lookups for certain hard to remember numeric values, and for internal use by elementals.js itself.
Code Formatting
Rule of 76
Where possible the elementals.js codebase tries to keep all lines at 76 characters or less by inserting carriage returns and clear tab indentation as needed to aid in code clarity. Whilst not always possible, it's just good practice.
Tabs vs. Spaces
Elementals is written using the hybrid approach, where all LEADING indentation is handled with tabs, and all 'inside a line' indentation is handled with spaces. This allows maintainers and editors to set the tab indent in their editors to whatever they are most comfortable with. If at any time you begin to feel uncomfortable, use the pretty printer of your choice to change it, we can always use our pretty-printer to change it back!
Though PERSONALLY I, Jason M. Knight, head maintainer and developer, use tabs set to two space widths. You feel like something else, DO it. If you have enough code or enough formatting that this becomes an issue, there's something WRONG with the codebase!
Really most developers waste too much time arguing over something that can so easily be changed on the fly by any decent editor or with minimal assistance from formatting tools.
Whitespace and operators
All major operators should have at least on space before and after them for clarity, whilst anything comma delimited should have no space before the comma and at least one space after. Oh noes, extra characters -- it's not like minification for DEPLOYMENT doesn't strip them out anyways!
Verbosity
Where possible variable names should be reasonably verbose so as to avoid the need for extra comments. Good rule of thumb? If the code is well tabbed, spaced, ruled, and uses verbose function and variable names, the need for excess comments should diminish many-fold!
Block Comments
Major blocks of code will be started with comments that have three asterisks before and after their text, one comment for *** START xxx *** and one for "*** END xxx ***" as appropriate. Subsections will say "start" and "end" in the same way but without the asterisks.
When a function or object method is closed, a comment should be placed after the closing bracket, or the semi-colon/comma that follows to say what is being closed. In this case the word "end" is not used since that's what the "}" means -- likewise a starting comment is unnecessary since we already say we're starting something like "function doWhater() {". Pointlessly redundant commenting is almost as bad as having none!
Terminology
The elementals project uses the following terms a good deal -- the manner in which they are used is often inconsistent across languages, which is why I thought it might be good to state the manner in which we are using them.
- Class or Prototype
- An object prototype, aka a function/object that you would not call directly, but instead create a copy of using "new"
- Constructor
- A function that creates and initializes an object, returning that new object.
- Destructor
- A function or method that 'shuts down' an object destroying it. TECHNICALLY JavaScript doesn't have proper constructors or destructors, but we can fake the behavior.
- Method
- A function attached to an object as a property.
- Object
- A live/working instance of a Class (or if you prefer, 'prototype')
- Parameter
- A variable, function, or object passed to a function or constructor.
- Property
- A variable, function, or object that is attached to an object.