Page History
...
DSpace Java Style Guide (Adopted 2018, for DSpace 7.x and above)
Info | ||
---|---|---|
| ||
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.
|
- 4-space indents for Java, and 2-space indents for XML. NO TABS ALLOWED.
K&R style braces required. Braces are also required on all blocks.
Code Block if (code) { // code } else { // code }
Maximum length of lines is 120 characters (except for long URLs, packages or imports)
- No trailing spaces allowed (except in comments)
- Do not use wildcard imports (e.g.
import java.util.*
). Duplicated or unused imports are also not allowed. - Write Javadocs for public methods and classes. Keep it short and to the point.
- Javadoc
@author
tags are optional, but should refer to an individual's name or handle (e.g. GitHub username) when included
- Javadoc
Tokens should be surrounded by whitespace, e.g. http://checkstyle.sourceforge.net/config_whitespace.html#WhitespaceAround
Code Block // 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" }
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 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 = "";
No empty "catch" blocks in try/catch. A "catch" block must minimally 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 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; }
Any "utility" classes (a utility class is one that just includes 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 DSpace 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/ */
...
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 older style guidelines are 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. 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
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, 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.
- 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.
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 themaster
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.
- Enabling on
- 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.
In 2018, we decided to update our guide based on / inspired by these two guides:
- The Fedora project style guide at Code Style Guide
- The Google Java Style Guide https://google.github.io/styleguide/javaguide.html
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. (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/ (Tested and works to validate code. To format you must generate a formatter style following the steps here. It seems impossible to force eclipse to use braces on sinle-line if statement)
- NetBeans Checkstyle plugin: http://plugins.netbeans.org/plugin/3413/checkstyle-beans
...