As of Feb 2018, the below DSpace Java Style Guide is enforced on all Pull Requests to the "main" branch. Therefore, if a Pull Request to the "main" branch does not align with the below Style Guide, it will fail the build process within our GitHub CI.
|
K&R style braces required. Braces are required on all blocks.
if (code) { // code } else { // code } |
Maximum length of lines is 120 characters (except for long URLs, packages or imports)
import java.util.*
). Duplicated or unused imports are not allowed.@author
tags are optional, but should refer to an individual's name or handle (e.g. GitHub username) when includedTokens 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" } |
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 = ""; |
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 } |
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; } |
Any "utility" classes (a utility class is one that just includes static methods or variables) should have non-public (i.e. private or protected) 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 constructor that is non-public. private Constants() { } } |
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/ */ |
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.
(These instructions are based on IntelliJ 2021.2.3. They should apply to other recent versions, but some menus or settings may have changed.)
checkstyle.xml for DSpace
Make sure to select a Checkstyle version which is compatible with the version we use in our Parent POM. Find the version in this tag in that POM:
<dependency> <groupId>com.puppycrawl.tools</groupId> <artifactId>checkstyle</artifactId> <version>8.30</version> </dependency> |
+
in the table). Select our checkstyle.xml
checkstyle.xml
These instructions were created using Eclipse Neon. Note: Eclipse Che (Codenvy) does not seem to support checkstyle.
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
(Please help us enhance these instructions to provide a step-by-step configuration for Eclipse)
These instructions worked for NetBeans 8.2.
The plugin still works in Apache NetBeans 12.6. It can be obtained at https://www.sickboy.cz/checkstyle/download.html. The instructions above should still work.
These instructions are for VSCode version 1.63.2.
Checkstyle for Java
extension by ShengChen. Follow the configuration docs for the plugin. The important parts are: set the configuration file, by right clicking the checkstyle.xml
file and select Set the Checkstyle Configuration File
. You will need to use the command Checkstyle: Set the Checkstyle Version
(Help>Show All Commands, or hit F1 on your keyboard) to manually set the Checkstyle version to 8.30
. The extension will automatically download the required checkstyle jar file if it needs to. Other versions of Checkstyle jar are known to not work (8.18 and 9.2.1 as of this writing all currently throw errors). The DSpace pom.xml file pins the version of checkstyle to 8.30, we should use that version in VSCode.settings.json
file for VScode): add this to your settings.json
file: "java.completion.importOrder": ["#","java","javax","com","org"],
If you do not use one of the above IDEs to write your code, you can always verify your code from the command-line using the following Maven command. This command can be run from the root source directory ([dspace-source]) to check all source code, or from within an individual module (e.g. [dspace-source]/dspace-api/) to only check that module.
# If the below checkstyle:check command complains about missing SNAPSHOT dependencies, then you may need to first run: # mvn install # This checks the code style of all source code under the current directory # It also ensures all source code has the required license header. mvn -U checkstyle:check license:check |
*.java, *.xml
" (As we'll only bulk reformat Java and XML files)Finally, run Checkstyle against the module. There likely will still be a few failures to fix manually.
# mvn install (Only necessary if checkstyle:check below complains about missing SNAPSHOT dependencies) mvn -U checkstyle:check |
Also double check license headers are still accurate. Sometimes these get "munged" during bulk reformat (as IDEA occasionally tries to merge nearby comments into one larger comment)
mvn license:check |
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 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:
The DSpace Typescript Style Guide is enforced on all Pull Requests to the "main" branch. Therefore, if a Pull Request to the "main" branch does not align with the below Style Guide, it will fail the build process within our GitHub CI.
|
For the DSpace Angular UI (written in TypeScript), we use ESLint to validate the style of all Typescript (*.ts) files.