This page serves as a guide to assist the Coders of this project in creating readable, maintainable, consistent, and—dare we say—beautiful code.

The reason I emphasize the word "guide" is that there will be possible exceptions. Read on.

Terminology

• Brackets: []. Commonly used for array literals and array indices.
  
• Braces: {}. Commonly used for enclosing new scopes; also used for Hash literals in Ruby.
• Parentheses: (). Commonly used for function arguments, sometimes for array/tuple literals.

General Formatting

 Indentation Size

All code is to be indented with hard tabs (i.e., actual tab characters). Spaces are to be used for alignment purposes (see #2 in Where to Change Indentation Levels below).

Most of us will be viewing the code at four spaces per tab—or whatever is standard for the language we decide on. If the language usually uses soft tabs, we'll do that.

This rule may be changed when we decide on a language. I would prefer to use the tab width that is "standard" for that language, but maintaining soft tabs (for the reason mentioned above.

 Where to Change Indentation Levels

1. Changes of scope. This means places where the scope enters or leaves a function/method, class definition, etc. Use tabs here.

   int main(int argc, const char **argv) {
       foo(); // Indentation level increases here because we're inside the braces of the main() function.
   } // The closing brace goes back a level.

2. Unfinished brackets/braces/parentheses. This means wherever you start something like an array or a list of arguments and don't finish it on the same line. The remaining arguments/items are to be indented with spaces (see above) to the exact horizontal position of the first item.

   doCoolThings("an argument", anotherArgument,
                469.1, moreStuff); // Keep in mind that these are all spaces for alignment.

Comments

Comment well, comment often! You're not the only one who needs to understand what your code does. And you may not even understand it later.

WHENEVER YOU DO NOT COMMENT YOUR CODE, GOD KILLS A KITTEN.

 A general rule: if you have code and a comment on the same line, and the comment gets to the point where it needs to be on a separate line, move the entire comment to the area above the line of code.

aFunction(arguments); // This calls the aFunction() function.

// This function call to aReallyLongFunctionName will
// call the function with several arguments for such and such
// reason. See how this is too long for a single line?
aReallyLongFunctionName(lots, of, lengthy, arguments);

You must leave a space between the code and the comment that comes after it if they are on the same line.