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.