Formatting Rules

The code style conventions used in the project are based on the style-guide defined of Fedora-3. They should prevent commits cluttered with format changes.

Here are the major rules:

  1. Four space indents for Java, and 2-space indents for XML. NO TABS

  2. K&R style braces

    if (code) {
  // code
} else {
  // code
}
  3. Do not use wildcard imports
  4. Write Javadocs for public methods and classes. Keep it short and to the point
  5. Avoid public instance variables; use accessors
  6. Use public methods sparingly; implementation details are not public
  7. Maximum length of lines is 120 characters.

  8. Create Javadocs for types of at least the following descriptivity

    /**
 * @author Joe Developer
 */
public class MyClass

  9. Each source file should contain a license header much like the following (which can be automatically added by running   mvn license:format):

    /*
 * The contents of this file are subject to the license and copyright
 * detailed in the LICENSE and NOTICE files at the root of the source
 * tree.
 */

IDE Setups

IDE settings are located in the project source. IDE users are strongly recommended to apply these formatting settings.

Checkstyle

We use checkstyle enforcement to our modules (meaning, if you violate some of the major style rules, the build will fail).

To check for violations, run the following command:

mvn checkstyle:check
  • No labels

2 Comments

  1. Edwin Shin

    There is some impedance mismatch between the Eclipse formatter rules and Checkstyle.

    For example, per Feature Request #934551 (which has been open for over a year), Checkstyle doesn't allow for a "throws" declaration that has wrapped to a new line to be indented further than the method body:

    Checkstyle formatting
    public LegacyMethod(final Event jcrEvent, final Node resource)
        throws RepositoryException {
        this(EntryFactory.newEntry());

    But Eclipse (and the standard Java Code Conventions) prefer a further indenting:

    Eclipse formatting
    public LegacyMethod(final Event jcrEvent, final Node resource)
             throws RepositoryException {
        this(EntryFactory.newEntry());

    The workaround in Eclipse is a hack if you have save actions defined (i.e. Eclipse will re-format your changed lines according to your settings, despite your efforts to manually adjust formatting to match the checkstyle requirements):

    1. "Correct" the indentation as required by Checkstyle.
    2. Save. Eclipse will automatically reformat the line back, removing the correction you just made.
    3. Undo.
    4. Save.

  2. A. Soroka

    Thanks, Edwin Shin. I was just about to write a message asking this very question.

     

All content on the LYRASIS Wiki is licensed under the CC BY (Attribution) license, unless otherwise noted.