Caveat

X10 has an extensive code base that has been developed over the last decade by a large 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 trying to apply more uniform coding conventions to newly developed code, to clean up older code, and to automate some basic checking of those coding conventions that are uniformly followed already.

Whitespace

  • 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:
      // vim:tabstop=4:shiftwidth=4:expandtab

      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).

/*
 *  This file is part of the X10 project (http://x10-lang.org).
 *
 *  This file is licensed to You under the Eclipse Public License (EPL);
 *  You may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *      http://www.opensource.org/licenses/eclipse-1.0.php
 *
 *  (C) Copyright IBM Corporation 2006-2015.
 */

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 public 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.lang and x10.array for examples.