Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

158 lines (100 sloc) 5.306 kb
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.
Jump to Line
Something went wrong with that request. Please try again.