Code Style Guide (WIP)

Existing Style Guide

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.

Alternative Style Guides

Google Java Style Guide

The Google Java Style Guide is at https://google.github.io/styleguide/javaguide.html

Some of the primary differences of this style include:

• Longer lines (100 characters vs the 80 chars required by Sun)
• K&R style brackets/braces (https://google.github.io/styleguide/javaguide.html#s4.1-braces). This is the same as the Sun style, but different from our style
• 2-space indentation (vs 4-space indentation): https://google.github.io/styleguide/javaguide.html#s4.2-block-indentation
• Requires UTF-8 encoding (no encoding required by Sun)

Fedora Java Style Guide

The Fedora project has its own style guide at https://wiki.duraspace.org/display/FF/Code+Style+Guide

Some of the primary differences of this style include:

• Longer lines (than both Google and Sun) at 120 characters
• K&R style brackets/braces
• 4-space indentation (same as our current guide, but different from Google)

Resources

Checkstyle verification

While not yet implemented, verification of code style guidelines is likely to be implemented via Checkstyle.  Checkstyle is widely used in the Java world, and supports both Google and Sun Java conventions, as well as custom configurations. 

• A Maven plugin for checkstyle verification exists (which can validate styles on build): maven-checkstyle-plugin
• Existing Checkstyle configurations
  • The Fedora project has its own Checkstyle configuration (for its style guide): https://github.com/fcrepo4/fcrepo-build-tools/blob/master/src/main/resources/fcrepo-checkstyle/checkstyle.xml
  • A Google Checkstyle configuration is at: https://github.com/checkstyle/checkstyle/blob/master/src/main/resources/google_checks.xml
  • A Sun Checkstyle configuration is at: https://github.com/checkstyle/checkstyle/blob/master/src/main/resources/sun_checks.xml
• Early notes on enabling Checkstyle in DSpace codebase are available in this gist: https://gist.github.com/tdonohue/b51b919b87b5f08930fac4fd9d52b9ae
  • Note: Currently, it borrows heavily from the Fedora Checkstyle configuration (just as an example). We'd need to update the actual checkstyle.xml based on our final style guide.

IDE Support

Most major IDEs include plugins that support Checkstyle configurations. This plugins usually let you import an existing "checkstyle.xml" configuration to configure your IDE to use and/or validate against that style. (Please note: we have not tested all these plugins as of yet, so mileage may vary until we test/verify the plugin is usable)

• IntelliJ IDEA Checkstyle plugin: https://plugins.jetbrains.com/plugin/1065-checkstyle-idea  (Tested and works to format & validate code)
• Eclipse Checkstyle plugin: http://eclipse-cs.sourceforge.net/
• NetBeans Checkstyle plugin: http://plugins.netbeans.org/plugin/3413/checkstyle-beans