Page tree
Skip to end of metadata
Go to start of metadata

This Style guide is unofficial as of yet. Please see the Code Contribution Guidelines page for our old code style recommendations, which are still currently in effect.

Existing DSpace Java 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

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)

If you would like to comment on this proposal, please add your thoughts to this Pull Request:

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 required on all blocks.

    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.

  6. No trailing spaces allowed (except in comments)
  7. Tokens should be surrounded by whitespace, e.g.
  8. Each source file must contain the required 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

Other Java Style Guides

Google Java Style Guide

The Google Java Style Guide is at

Some of the primary differences of this style include:

Fedora Java Style Guide

The Fedora project has its own style guide at

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)


Checkstyle verification

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

Branches to enable Checkstyle on?

Which git branches would we want to enable Checkstyle on?

  • Initially, likely just the master branch, and perhaps just specific modules (e.g. "dspace-spring-rest") on the master branch.
    • Enabling on master branch only may complicate cherry-picking of code changes from other branches (as line numbers, spacing, etc may change when the code is updated to use the latest DSpace Style Guide)
    • However, if we implement this module-by-module (starting with "dspace-spring-rest", the new DSpace 7 REST API), this may temporarily minimize the cherry-pick conflicts while also ensuring any new code meets the new style guidelines.
  • Backporting to other branches (dspace-6_x, dspace-5_x, dspace-4_x) is yet to be determined.
    • Backporting might affect local checkouts/forks of these branches, as a large number of files will change at once. This has the potential to cause local merge conflicts to occur, if an institution has made Java code customizations.

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. (Please note: we have not tested all these plugins as of yet, so mileage may vary until we test/verify the plugin is usable)

Fixing the codebase

Cleanup via IDEA

  • Install checkstyle plugin:
    • File →  Settings →  Plugins
    • Restart IDE
  • Configure it to use our custom checkstyle.xml
    • File →  Settings →  Checkstyle
    • Add a "Configuration File" (press the + in the table). Select our checkstyle.xml
    • Make it "Active"
    • Click Apply
  • Update IDEA's Code Style to obey the Checkstyle Rules (See also
    • File → Settings → Editor → Code Style
    • Click the small gear icon next to "Scheme", Select "Import Scheme" → CheckStyle Configuration
    • Select our checkstyle.xml
    • Click OK
    • Click Apply
  • Update IDEA's Java code style to align with a few specific CheckStyle rules (which don't seem to be auto updated per previous step)
    • First, order import statements per our rules
      • File → Settings → Editor → Code Style → Java → Imports
      • In the "Import Layout" section, ensure  the settings are in this order
        • "import static all other imports"
        • <blank line>
        • "import java.*"
        • "import javax.*"
        • <blank line>
        • "import all other imports"
      • Once reordered, click OK
    • Then, update to auto-wrap lines at the right margin
      • File → Settings → Editor → Code Style → Java → Wrapping and Braces
      • CHECK "Ensure right margin is not exceeded"
      • Click OK
  • Update IDEA's Javadoc settings to not insert "<p>" on blank Javadoc lines (as this will cause IDEA to change all our DSpace license headings improperly)
    • File → Settings → Editor → Code Style → Java → JavaDoc
    • UNCHECK "Generate <p> on empty lines"
    • Make sure "Keep empty lines" is checked
    • Click OK
  • Now open up any Java source file. You'll see Checkstyle warnings appear (if any) in RED
  • Select "Code -> Reformat Code" (Ctrl + Alt + L) to reformat the open source file based on Checkstyle rules.
    • If any import statements use an asterisk, you will also need to do "Code -> Optimize Imports" (Ctrl + Alt + O) to correct those.
  • NOTE: You can also reformat code in bulk in IDEA:
    • Right click on a single directory / module
    • Select "Reformat Code"
      • Check "Optimize imports"  (This will remove any import statements with an asterisk)
      • Leave "Rearrange entries" unchecked (This will rearrange methods/variables based on arrangement settings in IDEA. We don't need this)
      • Under "Filters" → Check "File Masks" and enter in "*.java, *.xml"  (As we'll only reformat Java and XML files)
      • Click Run
  • Finally, run Checkstyle against the module. There likely will still be a few failures to fix manually.

    mvn install
    mvn -U checkstyle:check

  • No labels

1 Comment

  1. 'extends' and 'implements' should be treated as 'throws' is.