Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

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):

Code Block
themeEclipse
/*
 * Copyright 20192020 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:

Code Block
themeEclipse
Copyright [year] [owner]

The attribute should be prefixed with "Portions" for changes to existing files:

Code Block
themeEclipse
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:

Code Block
themeEclipse
Portions copyright 2011-2016 ForgeRock AS.

...

  • toggle Checkstyle on and off

    Code Block
    themeEclipse
    // @Checkstyle:off
    ... ignored
    // @Checkstyle:on
    
  • instruct Checkstyle to ignore the next line

    Code Block
    themeEclipse
    // @Checkstyle:ignore
    ... ignored
    ... checked
    
  • instruct Checkstyle to ignore next N lines (-ve means previous lines)

    Code Block
    themeEclipse
    // @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):

Code Block
themeEclipse
<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 precommit profile:

Code Block
themeEclipse
mvn -Pprecommit clean install

...

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 false:

Code Block
themeEclipse
mvn -P precommit -DcheckstyleFailOnError=false clean install

Or in the Maven pom.xml file:

Code Block
themeEclipse
<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):

Code Block
themeEclipse
<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>

...

  1. Include the sample code in your tests.
  2. Add JCite as a dependency of the Javadoc Maven plugin, as in the following example.

    Code Block
    languagethemehtml/xmlEclipse
    <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>
    
  3. Cite the sample code as described in http://www.arrenbrecht.ch/jcite/javadoc.htm.
  4. Build and check the Javadoc.

...

  1. Before reformatting your code in order to comply with the coding conventions be aware of the following:
    1. reformatting will not add missing Javadoc!
    2. reformatting may introduce widespread changes which will make it harder to back-port fixes to branches because it will not be possible to apply patches
    3. widespread changes resulting from formatting will make tools like Fisheye less useful because the revision annotations will all refer to the same reformat revision, giving the appearance that the file was entirely written by a single user. To see the remaining revision history it will be necessary to step back to a revision before the reformatting occurred
    4. 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:

      Code Block
      themeEclipse
      // This is a comment which uses multiple single-line comments "//" instead
      // of a multi-line comment block using "/* ... */"
      

      Could become:

      Code Block
      themeEclipse
      // This is a comment which uses multiple single-line comments "//"
      // instead
      // of a multi-line comment block using "/* ... */"
      
  2. The Checkstyle indentation rule contains a bug which causes it to incorrectly flag correctly indented throws declarations as errors. The Checkstyle Maven integration includes a fix for this, however it will not be available if running Checkstyle outside of Maven, e.g. within an IDE or as part of an Ant build.