Page History

...

...

DSpace Java Style Guide

...

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

Bolded rules are a change from our current Style Guide.

1. 4-space indents for Java, and 2-space indents for XML. NO TABS ALLOWED.
   1.  Only exception is throws clause, which should be indented 8 spaces if on a new line

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

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

   
   

3. Do not use wildcard imports (e.g. import java.util.*). Duplicated or unused imports are also not allowed.
4. 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
      

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

6. No trailing spaces allowed (except in comments)

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

   Code Block
   // This is not valid -- needs whitespace around tokens String []={"one","two","three"} // This is valid -- whitespace 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.

   Code Block
   // This is not valid -- three variables 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.  At least include a comment as to why the catch is empty, e.g. 

   Code Block
   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.

    Code Block
    // This is not valid -- doesn't include a "default" and also is missing a "break" in first "case" switch (myVal) { case "one": // do something case "two": //do something else break; } // This *is* valid. Has all necessary breaks, and includes a "default" 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 has static methods or variables) should have private constructors,

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:

• Curly braces must be on new lines.
• Source files must have a copy of the copyright Duraspace notice and BSD license at the top (see Licensing of Contributions below). Also take a look at Copyright and Licensing.
• You must use 4-space tabulation.
• 'else' should be on a new line. 'else if' stays on one line.
• Users of the Eclipse IDE can have eclipse do the formatting automatically using this profile: - Dspace-eclipse-format.xml. See the Eclipse section below for details of how to apply this profile.

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 existing style guidelines are 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.  We should consider whether we continue to base our style off this outdated guide, use a more modern guide, or develop our own guide.

Proposed DSpace Java Style Guide (work-in-progress - not yet approved)

Bolded rules are a change from our current Style Guide.

1. 4-space indents for Java, and 2-space indents for XML. NO TABS ALLOWED.
   1.  Only exception is throws clause, which should be indented 8 spaces if on a new line

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

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

2. Do not use wildcard imports (e.g. import java.util.*). Duplicated or unused imports are also not allowed.
3. 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
      

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

5. No trailing spaces allowed (except in comments)

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

   Code Block
   // This is not valid -- needs whitespace around tokens String []={"one","two","three"} // This is valid -- whitespace around all tokens String [] = { "one", "two", "three" }

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

   Code Block
   // This is not valid -- three variables declared on one line String first = "", second = "", third = ""; // This is valid, each statement is on its own line String first = ""; String second = ""; String third = "";

   No empty "catch" blocks in try/catch.  At least include a comment as to why the catch is empty, e.g. 

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

   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.

   Code Block

   // This is an example notclass validof -- doesn't include a "default" and also is missing a "break" in first "case" switch (myVal) { case "one": static constants public class Constants { public static final String DEFAULT_ENCODING = "UTF-8"; public static final String ANOTHER_CONSTANT = "Some value"; // As dothis something is a case "two": //do something elseutility class, it MUST have a private, empty constructor break; } // This *is* valid. Has all necessary breaks, and includes a "default" switch (myVal) { case "one": // do something break; case "two": //do something else break; default: // do nothing break; }

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

   Code Block
   // 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() { } }

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

   Code Block/** * 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/ */

   private Constants() { } }

   
   

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

   Code Block
   /** * 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:

• Curly braces must be on new lines.
• Source files must have a copy of the copyright Duraspace notice and BSD license at the top (see Licensing of Contributions below). Also take a look at Copyright and Licensing.
• You must use 4-space tabulation.
• 'else' should be on a new line. 'else if' stays on one line.
• Users of the Eclipse IDE can have eclipse do the formatting automatically using this profile: - Dspace-eclipse-format.xml. See the Eclipse section below for details of how to apply this profile.

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 existing style guidelines are 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.  We should consider whether we continue to base our style off this outdated guide, use a more modern guide, or develop our own guide.

Other Java Style Guides

Google Java Style Guide

...