This document covers common coding styles and guidelines for all ForgeRock products.
The ForgeRock Java coding style is loosely based on the Sun Java conventions. We provide a set of Checkstyle rules which can be used to enforce the code style, as well as integration for Maven based projects.
All new source files must begin with the following copyright notice, which should be adapted accordingly for non-Java source code (e.g. XML, properties, etc):
/* * Copyright 2020 ForgeRock AS. All Rights Reserved * * Use of this code requires a commercial software license with ForgeRock AS. * or with one of its affiliates. All use shall be exclusively subject * to such license between the licensee and ForgeRock AS. */
All source files should contain copyright attributions for the people or organizations who have contributed the code. For new files this should be of the form:
Copyright [year] [owner]
The attribute should be prefixed with "Portions" for changes to existing files:
Portions copyright [year] [owner]
When multiple contributions have been made in different years by the same contributor a year range should be used and kept up to date, for example:
Portions copyright 2011-2016 ForgeRock AS.
Note that copyright attributions DO NOT need to include a (c) symbol nor the phrase "All rights reserved". In addition, projects MUST include the CDDL license in its entirety in the project relative location
The ForgeRock Java code style rules are based on the Sun Java conventions with some deviations, the key points being:
package-info.javacontaining at least a short summary of the package
package-info.javafile with at least a simple one line summary of the package's content
NOTE: Javadoc is NOT required for unit tests.
List<T>) MUST begin with a single upper-case letter and be followed by zero or more digits.
static final)MUST contain only upper-case letters, digits, or underscores
import java.util.*is not allowed. (hint for IntelliJ)
import static org.junit.Assert.*is no longer allowed
File > Other Settings > Default Settings > Editor > Code Style > Java > Imports (tab)
You can prompt IntelliJ to organize imports for a given file using Code > Optimize Imports or by clicking ALT + SHIFT + O or Control + Option + O.
> In eclipse these may be set by going to either Eclipse (OSx) or Window (Windows & Linux) > Preferences > Java > Code Style > Organize Imports and making the following selections;
casestatements aligned with their associated
switch, and continuation lines 8 characters
catchclauses are not allowed
equals()MUST also override
A complete set of Checkstyle rules which enforce the ForgeRock coding style can be found here:
Sometimes Checkstyle validation incorrectly reports an error and there is no easy workaround. In these rare cases you may choose to temporarily disable Checkstyle from within your source code using one of the following source code annotations:
toggle Checkstyle on and off
// @Checkstyle:off ... ignored // @Checkstyle:on
instruct Checkstyle to ignore the next line
// @Checkstyle:ignore ... ignored ... checked
instruct Checkstyle to ignore next N lines (-ve means previous lines)
// @Checkstyle:ignoreFor 2 ... ignored ... ignored ... checked
Full Maven integration has been provided for projects which declare
forgerock-parent version 1.1.0-SNAPSHOT or later as their parent (directly or indirectly):
<parent> <groupId>org.forgerock</groupId> <artifactId>forgerock-parent</artifactId> <version>1.1.0-SNAPSHOT</version> </parent>
Once the dependency is declared Checkstyle is automatically available via the
mvn -Pprecommit clean install
By default Checkstyle will use the default set of rules and copyright notice listed above . In addition, the
precommit profile will fail the build if any validation errors are encountered.
For some existing projects it may not be feasible to fix all of the pre-existing Checkstyle violations, in which case the
precommit profile should be configured to not fail the build. This can be achieved by setting the
checkstyleFailOnError property to
mvn -P precommit -DcheckstyleFailOnError=false clean install
Or in the Maven
<properties> <checkstyleFailOnError>false</checkstyleFailOnError> </properties>
In some very rare cases it may be necessary to use an alternative set of Checkstyle rules or an alternative copyright template. This can be achieved using the following Maven properties (shown below with their default values):
<properties> <checkstyleSourceConfigLocation>org/forgerock/checkstyle/check-src-default.xml</checkstyleSourceConfigLocation> <checkstyleUnitTestSuppressionsLocation>org/forgerock/checkstyle/unit-test-suppressions.xml</checkstyleUnitTestSuppressionsLocation> <checkstyleHeaderLocation>org/forgerock/checkstyle/default-java-header</checkstyleHeaderLocation> </properties>
Here is the the Eclipse formatter for the ForgeRock coding style : eclipse_profile_formatter_ForgeRock.xml .
And here is the IntelliJ code style settings: ForgeRock.xml (installation instructions)
When committing code it is essential that others can quickly get an idea of what the commit relates to, and also find more information on the issue and review. A message must always be provided when committing to trunk, sustaining or release branches/tags and we have some simple guidelines for writing them.
State in up to 50 chars how this commit changes the product. Begin with a capital letter and don’t end with a full stop. Write as if completing the sentence "If applied, this commit will..."
Example: AME-9876 CR-1234 Add new authentication module for device auth
Avoid broken code samples in Javadoc by using code citations rather than inline code in comments. The code citations are resolved when the Javadoc is built.
To cite a code samples in a Javadoc comment, use the JCite code citation system.
Add JCite as a dependency of the Javadoc Maven plugin, as in the following example.
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <configuration> <taglet>ch.arrenbrecht.jcite.JCiteTaglet</taglet> <tagletArtifact> <groupId>org.mcraig</groupId> <artifactId>jcite</artifactId> <version>1.13.0</version> </tagletArtifact> <sourcepath>src/test/java</sourcepath> <additionalJOption>-J-Djcitesourcepath=src/test/java</additionalJOption> </configuration> </plugin>
IDEs such as Eclipse will attempt to rewrap single-line comments. If multiple single lined comments have been used instead of a block comment, then the comments may become mangled during reformatting. For example:
// This is a comment which uses multiple single-line comments "//" instead // of a multi-line comment block using "/* ... */"
// This is a comment which uses multiple single-line comments "//" // instead // of a multi-line comment block using "/* ... */"