Caveat

X10 is a still maturing code base that has been written over several years by a number of people. You will find that some of the code does not live up to product quality standards. Don't hesitate to help rectify this by contributing clean-ups, bug fixes, and missing documentation to the project. We are in the process of consolidating and simplifying the codebase at the moment and trying to apply more uniform coding conventions and automate some basic checking of those coding conventions that are uniformly followed already.

Whitespace

• Be sure that your .subversion/config file has auto-props setup so that newly added source files will have their svn:eol-style and svn:mime-type properties set correctly.  Here's a sample config file that you can use.

• Please avoid gratuitous whitespace changes in your commits. You are, of course, welcome to change the indentation and whitespace on the lines you're modifying.
  • We will arrange in advance periodic wholesale whitespace commits that modify multiple files at the same time.

• For Java, C++, and X10 code, use 4-space indenting with no tabs and no trailing whitespace. Most editors can be configured to do this automatically.
  • In Eclipse, go to Preferences->General->Editors->Text Editors and set Displayed tab width to 4 and check the Insert spaces for tabs checkbox. We also have an X10-specific set of formatter preferences that will be posted shortly.
  • In vim, issue the following command: ":set tabstop=4 shiftwidth=4 expandtab". You can also add a modeline in a comment at the bottom of any Java, C++, or X10 source file, as follows:

    Many files already have this modeline.

• Try to avoid making lines longer than 132 characters, but also don't go out of your way to make them fit in 80 characters.

Coding style

• For Java, our basic coding style guidelines are defined with reference to the Sun® Microsystems "Code Conventions for the Java™ Programming Language", with a few exceptions listed below. Most of the style guide is intuitive; however, please read through the document (or at least look at its sample code).

• If you use Eclipse to edit your Java source, there is Eclipse Formatter Profile checked in to svn at x10.common/contrib/eclipse/jdt/X10JavaFormatting.xml that you can use.

• Put braces ("{" and "}") around loop bodies and conditional clauses that are not on the same line as the header.

• Do not put the opening brace on a new line.
  • An exception is in method headers, if the signature takes up more than one line – then put the brace on the next line with the same indentation as the first line of the method signature.

File Headers

Every file should begin with the standard license and copyright header shown below (adjusted to use the comment characters appropriate to the source file).

Javadoc/X10doc requirements

The following applies to both Java code and X10 code.

All files should contain descriptive comments in Javadoc™ form so that documentation can be generated automatically. Of course, additional non-Javadoc source code comments should appear as appropriate.

1. All classes and methods should have a block comment describing them
2. All methods contain a short description of their arguments (using @param), the return value (using @return) and the exceptions they may throw (using @throws).
3. Each class should include @see and @link references as appropriate.

The X10doc format is very similar to that of Javadoc. Please see the X10 files in x10.runtime for examples.