DSpace Java Style Guide (Adopted 2018, for DSpace 7.x and above)

As of Feb 2018, the below DSpace Java Style Guide is enforced on all Pull Requests to the "master" branch. Therefore, if a Pull Request to the "master" branch does not align with the below Style Guide, it will fail the build process within Travis CI.

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

  2. K&R style braces required. Braces are required on all blocks.

    if (code) {
  // code
} else {
  // code
}


  3. Maximum length of lines is 120 characters (except for long URLs, packages or imports)

  4. No trailing spaces allowed (except in comments)
  5. Do not use wildcard imports (e.g. import java.util.*). Duplicated or unused imports are not allowed.
  6. Write Javadocs for public methods and classes. Keep it short and to the point.
    1. Javadoc @author tags are optional, but should refer to an individual's name or handle (e.g. GitHub username) when included

  7. Tokens should be surrounded by whitespace, e.g. http://checkstyle.sourceforge.net/config_whitespace.html#WhitespaceAround

    // This is NOT valid. Whitespace around tokens is missing
String []={"one","two","three"}

// This is valid. Whitespace exists around all tokens
String [] = { "one", "two", "three" }


  8. Each line of code can only include one statement.  This also means each variable declaration must be on its own line, e.g.

    // This is NOT valid. Three variables are declared on one line
String first = "", second = "", third = "";

// This is valid. Each statement is on its own line
String first = "";
String second = "";
String third = "";


  9. No empty "catch" blocks in try/catch.  A "catch" block must minimally include a comment as to why the catch is empty, e.g. 

    try {
  // some code ..
} catch (Exception e) {
  // ignore, this exception is not important
}


  10. All "switch" statements must include a "defaut" clause.  Also, each clause in a switch must include a "break", "return", "throw" or "continue" (no fall throughs allowed), e.g.

    // This is NOT valid. Switch doesn't include a "default" and is missing a "break" in first "case"
switch (myVal) {
  case "one":
     // do something
  case "two":
     // do something else
     break;
}

// This is valid. Switch has all necessary breaks and includes a "default" clause
switch (myVal) {
  case "one":
     // do something
     break;
  case "two":
     // do something else
     break;
  default:
     // do nothing
     break;
}


  11. Any "utility" classes (a utility class is one that just includes static methods or variables) should have private constructors, e.g.

    // This is an example class of static constants
public class Constants {
   public static final String DEFAULT_ENCODING = "UTF-8";
   public static final String ANOTHER_CONSTANT = "Some value";

   // As this is a utility class, it MUST have a private, empty constructor
   private Constants() { }
}


  12. Each source file must contain the required DSpace license header, e.g.

    /**
 * 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 and available online at
 *
 * http://www.dspace.org/license/
 */


Old DSpace Java Style Guide (for versions 6.x and prior)

Per the Code Contribution Guidelines page (see "Coding Conventions" section), our existing style guide is listed as follows:

Your code needs to follow the Sun Java code conventions with the following minor modifications:

Your code should be well commented with Javadoc (including package and class overviews). All code contributions must come with Documentation. At a bare minimum, this should include Technical Documentation covering all configuration options and/or setup. See Documentation Contributions below for more details.

These older style guidelines were based heavily on the Sun coding conventions (circa 1999) which are no longer maintained, but still available at http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html

Because the Sun Java style guide is no longer maintained, it will not be keeping up with current Java style best practices, features, etc.  

In 2018, we decided to update our guide based on / inspired by these two guides:

Resources

IDE Support

Most major IDEs include plugins that support Checkstyle configurations. The plugin usually let you import an existing "checkstyle.xml" configuration to configure your IDE to use and/or validate against that style.

Fixing the codebase

Cleanup via IDEA

Configure IDEA for bulk cleanup
Use IDEA to perform bulk cleanup