Java Coding Conventions

Class Structure and Member Sort Order

Java types should have the following member order:

1. Nested Types (mixing inner and static classes is okay)
2. Static Fields
3. Static Initializers
4. Static Methods
5. Instance Fields
6. Instance Initializers
7. Constructors
8. Instance Methods

Members that fall into the same category (e.g. static methods) should also be sorted in this order based on visibility:

1. public
2. protected
3. default
4. private

All methods should be sorted alphabetically. Sorting is optional but recommended for fields.

In ECLIPSE:

• Menu: Window -> Preferences
• Selection: Java -> Appearance -> Members Sort Order

Code Style Formatter

This is the file with the ECLIPSE conventions:

• etics-java-coding-conventions.xml: ETICS Java Coding Conventions v. 1.0
• etics-java-coding-conventions2.xml: ETICS Java Coding Conventions v. 2.0

(Version 2 uses the features added in Eclipse 3.4.0)

Indentation now changed to:

• Use only spaces (no tabs)
• 2 spaces indentation for blocks
• 4 space indentation after line wraps

How to load the file in ECLIPSE:

• Menu: Window -> Preferences
• Section: General -> Java -> Code Style -> Formatter
• Import...
• Select the xml file present in this page.

How to use the formatter:

• Ctrl + a select all the code
• Ctrl + i indent only (without full formatting)
• Ctrl + Shift + F full formatting

Other usefull shorcuts:

• Ctrl + Shift + O remove not used imports and adds the needed one

Clean Up conventions

This is the file with the ECLIPSE Clean Up conventions:

• etics-clean-up-profile.xml: ETICS Clean Up Profile v. 1.0

Imports

The ordering of import statements is from specific to generic:

* org.etics imports * Imports from third parties (com, junit, net, org) * java and javax

To exactly match the IDE settings, the imports should be:

* Alphabetical within each grouping. Capital letters are considered to come before lower case letter (e.g. Z before a). * There should be a blank line between each major grouping (google, com, junit, net, org, java, javax).

In ECLIPSE:

• Menu: Window -> Preferences
• Selection: Java -> Code Style -> Organize Imports -> Import...

This is the file with the conventions:

• etics.importorder: ETICS Import Oder v. 1.0

Acronyms and Abbreviations

Acronyms and abbreviations should all be in the same case:

Good: XMLHTTPRequest Bad: XmlHttpRequest

Good: getCustomerID Bad: getCustomerId

Max Column marker

• Menu: Window -> Preferences
• Selection: General -> Editors -> Text Editors ->
• Enable Show print margin checkbox
• Set Print margin column to 80

Unit Testing

Unit tests are very important, and therefore strongly encouraged, adding new unit tests for new functionality or updating existing unit tests for bug fixes.

Tests for Java classes should be placed in a parallel source tree under test and the test class name should be suffixed with Test. For example:

src/org/etics/webservice/core/MyClass.java
test/org/etics/webservice/core/MyClass.java

The use of the parallel test tree has two major advantages:

* You can do package scope testing (vs. a tests subpackage). * There is a clear separation between production and test code making packaging easier. This reduces the number of build breaks and the amount of time spent updating build files.

Java Doc

What to document

• All not private methods members and classes must have JavaDoc documentation.
• If interfaces are fully documented, the implementation can reference to the interface for the functionality. It may add documentation on the way it is implemented.
• Private methods and members should have JavaDoc documentation.
• Packages must have documentation

How to document

Packages

Add a file called package-info.java directly inside the package with the following format (example from package org.etics.repository.webservice.archive):

/**
 * Provides the archive functionality.
 * This allows to browse contents of supported 
 * archives such as RPM, TAR, TAR.GZ, ZIP, etc.
 * <p>
 * In addition to the contents it is possible
 * to access the information stored in the
 * descriptors of the archives.
 */
package org.etics.repository.webservice.archive;

Classes and Interfaces

Add a comment before the class or interface name in the following format:

/**
 * Defines all operations
 * allowed to be performed on an archive
 * by the {@link ArchiveManager}.
 * 
 * @author Lorenzo Dini <Lorenzo.Dini@cern.ch>
 */
public interface Archive {

[...]

}

Methods

Add a comment before the method name in the following format:

   /**
     * Returns a list of all files contained in the archive.
     * 
     * @param location the repository location of the archive
     * @param delimiter the delimiter to be used to separate
     *       the archive location
     *       and the internal item location
     * @return an array of {@link org.etics.repository.webservice.model.File}
     *          with the list of files contained in the archive.
     *          Empty array (not null) if the archive is empty.
     * @throws Exception
     */
    public File [] listFiles(String location, String delimiter) throws Exception;

Members

Add a comment before the member declaration in the following format:

   /**
    * Version of the Repository Webservice
    * Must be changed at every new release
    */
   private static final String version = "1.2.0";
   
   /**
    * HTTP URL of the server in the following format http://hostname:8080
    * This URL is loaded at the first AXIS request
    */
   public static final String serverHTTPUrl;
   
   /**
    * HTTPS URL of the server in the following format https://hostname:8443
    * This URL is loaded at the first AXIS request
    */
   public static final String serverHTTPSUrl;

   static {
      //In order to get the MessageContext from the main thread
      //Axis fails if the MessageContext is requested by another Thread
      String servlet = (String) MessageContext.getCurrentContext().getProperty("transport.url");
      String serverUrl = servlet.substring(0, servlet.indexOf("/services/RepositoryService"));

      serverHTTPUrl = serverUrl.replaceAll("https://", "http://").replaceAll(":8443", ":8080"); 
      serverHTTPSUrl = serverUrl.replaceAll("http://", "https://").replaceAll(":8080", ":8443");
   }

JavaDoc TAGS

The full documentation of JavaDoc can be found here: http://java.sun.com/j2se/javadoc/writingdoccomments/

The commonly used are:

• @param to describe the parameters of a method

  @param x  the x-coordinate, measured in pixels

• @return to describe what is returned from a method, please describe border cases (i.e. case when null)

  @return the image at the specified URL

• @throws to list all the exceptions thrown, in case the exception name is ambiguous, please add a comment

  @throws NullPointerException if the input is null

• @author to add the author that is doing maintenance, needed only in the class or interface, not everywhere

  @author Lorenzo Dini Lorenzo.Dini@cern.ch

• @version to add the version and date of creation, if added, only in the class or interface, not everywhere

  @version 1.2.39, 28/02/2008

• @see to link for example the implementation to the interface

  @see org.etics.repository.archive.Archive#listFiles(String, String) listFiles interface definition

• @deprecated to deprecate a method or class

  @deprecated please use class {@link ArchiveDefinition} instead

• {@link ... } to link some other class, interface or method

  During the execution, the method {@link org.etics.repository.archive.Archive#listFiles(String, String)} is executed