JRuby Code Conventions
----------------------


This document summarizes the way we recommend to write source code for the
JRuby project.  Consistent code conventions improve readability, allowing
each one to understand new and existing code more quickly and thoroughly.


Rule of Thumb: 

 If not said otherwise below, as long as you keep in mind Sun's Java Code
 Conventions (http://java.sun.com/docs/codeconv/) you're doing well.


File Organization:

 Each source file should have a file comment starting in line 1 mentioning
 the project name, the CVS version information and a copyright statement.
 It must also reference the licenses but should not contain the full text.

 Let your IDE spell out all imports, do not use ".*" for imports.
 
 Remove unused imports.
 
 Use this order
 
  - file comment
  - package declaration
  - imports
  - javadoc comment
  - class or interface or enum definition
  - static variables
  - instance variables
  - constructors
  - ruby declarations
  - getter and setter methods
  - other methods
  - nested classes


Indentation:

 Indent by 4 spaces - do not use tab
 
 Do not use lines longer than 100 chars if possible.
 

Comments:
 
 Use plain english for all of your comments.

 Add only meaningful javadoc comments (do not leave meaningless IDE-generated
 comments in your code). The first sentence shall sumarize the element's
 purpose but must not simply rephrase the element's name.  Add more
 sentences if you need to add further description and/or examples. Try
 to explain what not how an element works.

 If you need to add other inline comments, prefer // over /* ... */.
 
 If you feel the urge to comment some block of code, think hard about 
 renaming an element and/or extracting a block into a well named method 
 first. Use inline comments to mark non-obvious design decision though.


Declarations:

 Use one declaration per line for variable declarations. Local variable
 declaration of the same type might be written in one line.
 
 If a non-local variable is set only once and only read thereafter, make
 it final.  Do not bother to declare parameters or local variables final
 unless it is required because of usage in inner classes.
 
 Use whole names for variables (except for mundane: e.g. 'i' for 'index').
 
 Put variables in scope they are used (not just at top). Try to initialize
 local variables always during declaration.  But do not add default
 initializations to mutable instance and class variables.
 
 Prefer constructors with arguments over non-arg constructors plus a list
 setters to initialize objects.  A constructed object shall always be in
 a valid state.
 
 Use "Type[] name" instead of "Type name[]" for arrays.
 

Statements:

 Use one statement per line.
 
 Use curly braces {} always.  Put the { at the end of the line.  Put } always
 in a new line.  An else or catch or finally statement shall be put on the
 same line as the closing }. 
 
 Do not use superfluous (), especially not with return.
 
 Prefer "for (Iterator i = ...; i.hasNext();) {...}" over "while" as idiom
 for iterating iterators.
 
 Use "/* falls through */" comments in switch if you need to and try to
 put the default case at the end.  Always add a default case.  If you
 think, it cannot happen add a "throw new Error(); // cannot happen"
 instead.
 
 Never catch exceptions and ignore them (JumpException might be an exception).
 Just printing a stack trace isn't good either. That's temporary debug code 
 that should never be commited.
 
 Do not swallow exceptions if you raise another one. Always pass the causing
 exception with the new one - even for IOException which are lacking the usual
 constructor.  use "throw (IOException) new IOException(...).initCause(...);"
 
 Use early returns rather than late returns (avoid block nesting hell).
 Therefore do no use "if { return } else { return }".  The "else" should
 be removed.

 
Whitespaces:

 Separate operators with whitespaces, use a whitespace after , and ; in
 for loops. Do not whitespaces before ) and after ( in parameter lists.
 Do use a single whitespace after if, while, for, switch.  Do not use
 a whitespace after method names though.  Use a single white space after
 casts.
 
 
Naming conventions:

 Use small case for package names, do not use the "_"
 
 Use capitalized names for classes and interfaces.
 
 Use small case for method names, local and instance variables.
 
 Use upper case for static final constants.
 
 Use getXXX or isXXX for getter methods, setXXX for setter methods. Do not
 use getXXX for methods have side effects and do more than returning a value.
 Consider "findXXX", "createXXX", "toXXX", "asXXX".
 
 If the user has to manage resources, make it easy to find matching methods.
 Use open/close, new/destroy, alloc/free, add/remove, etc.
 

Best practices:

 Use "//TODO: jfklsjflkds" to mark missing parts.  Most modern IDE can
 find these comments and list them for easy reference.

 Do not, never, I repeat, never, use something like "if (expr == true)".
 Comparison with true or false can always be expressed directly with
 "if (expr)" or "if (!expr)".  The same goes for "if (expr) { return true; }
 else { return false; }".  This can always be expressed as "return expr;"
 
 Use small methods. 10-20 lines should be a good target.