This document describes conventions that all source code in the Ontopia project should follow. Code which does not conform to the conventions described here can be silently fixed by any committer.

If something is not specified in this document, Sun's Code Conventions for the Java Programming Language and How to Write Doc Comments for Javadoc should take precedence.

This document is merely a specification of the exceptions from Sun's recommendations.

All code must compile on Java 1.7. For more detail, see JavaVersionPolicy.

Create a new Java package for each self-contained project or group of related functionality. Create and use directories in accord with Java package conventions. All package names should be lowercase. Keep the names short.

Add a package.html file to each package directory. This file will be used by javadoc to include package level documentation. The extent of the documentation should be similar to what you'll find in the JDK API documentation.

Place each public class in a separate file. Avoid nested classes except in the case of one-shot usages where the class cannot conceivably be used outside of its context. Feel free to use internal classes.

The structure of the program file should be as follows:

*blank*
      Package name
*blank*
      Import list
*blank*
      Class documentation
*blank*
      Class/interface body

Example:

package net.ontopia.topicmaps.impl.virtual;

import java.util.HashMap;
import java.util.Map;
import net.ontopia.topicmaps.core.TopicIF;
  
/**
 * ...
 */

public class ClassName implements InterfaceIF {
  ...
}

Wildcard imports like import java.util.* should not be used.

Classes and interfaces should follow Sun's naming convention; CamelCase. Interfaces must have the suffix IF, e.g. MyInterfaceIF.

References to classes and interfaces should not contain package names. That is, refer to Baz, not to foo.bar.Baz.

Member variables should never be accessible from outside the instance of a class. Create bean property methods to make it available.

The exception to this rule is static final members (constants).

For indentation, use two space characters.

Tab characters are absolutely forbidden. Configure your editor to not save them; switch editor or write a script if necessary.

Using braces when the block only contains one line is optional.

The "{" bracket should be placed on the same line as the construct that starts the block. The "}" bracket should be placed on a separate line.

When wrapping lines break after the operator.

All methods must declare the non-runtime-exceptions that they may throw in their throws clause. If they may throw several, all must be listed, though shortening the list by listing base classes instead of all their children is encouraged, provided information is not lost. In particular, 'throws Exception' should never appear on any method, except in extreme cases, such as methods that are so generic that they may in fact throw any exception.

Similarly, 'catch (Exception e)' should not be used anywhere, since it may catch exceptions that should not be caught and thus hide problems. The exact exceptions that are being caught should be spelled out instead.

For similar reasons, empty catch blocks should be shunned (except in testing code where exceptions are expected), since they may also hide problems and make debugging difficult. If you know that the exception can never happen always raise an OntopiaRuntimeException with a message like '"(IMPOSSIBLE) " + e', and pass in the caught exception to preserve the stack trace.

Writing messages to System.out or System.err is forbidden, except in code which is only meant to be used on the command-line, such as the net.ontopia.topicmaps.cmdlineutils package.

Comments should be used to explain anything which is not clear from the code, especially where the code does something unusual. High-level explanations are good, but detailed line-by-line commentary on what's going on should be unnecessary.

Code should normally never be commented out in code that is checked in. Instead, delete the code.

All packages, classes, methods and fields should have javadoc comments attached to them. The recommended style is:

/**
 * LABEL: ...
 */

In other words the comments should start with "/" and end with "/". Each line in between should start with a single " ".

All comments should start with a single sentence that explains what the class does. This sentence will be extracted by the javadoc tool and used in summaries.

If the comment contains multiple paragraphs each paragraph should be marked up using the <p> element to make sure that the paragraphs are correctly formatted in an HTML browser.

When adding classes or methods to public APIs, always add a @since %NEXT% tag so that we can set correct since tags when making the release, and so that we remember to mention these changes in the whatsnew documents.

Sometimes the access specifiers (public, package, protected and private) does not convey enough information, or they are directly misleading, about when a construct can or should be used. There may be several reasons why this is so. An example is when two classes need to call each others methods, but they are placed in different packages, and the methods are not intended for the users of the system. Then they have to be declared as public, even though they are not part of a public API.

Adding prose explaining the situation is not easily recognizable to the human that is trying to get an overview of the API.

An elegant solution to this problem is to "label" the javadoc comments. ObjectPeople has been doing this in their TopLink product line with very good results.

The idea is that every javadoc comment starts with a label like "PUBLIC:". Public in this case means that the construct is part of the public api and that users should be free to use the construct as they please.

The available labels are:

• PUBLIC: the construct is part of the public API and users are free to use it as they see fit.
• INTERNAL: the construct is used internally by the system. Code outside the system should never use this construct even though they may do so according to the access specifiers.
• DEPRECATED: the construct has been deprecated and should no longer be used. An alternative construct is usually provided.
• EXPERIMENTAL: the construct is not yet approved as being part of the public api. The stability and result of using these methods is not guaranteed.

The @author tag should not be used, nor should authorship be indicated in any other way in the file.

The @Override tag should be used for methods which override a method declaration in a superclass. The @Override tag must not be used to indicate that the method belongs to an interface (that's a Java 6 feature). Take care if your IDE tries to be smart and adds the @Override tag automatically to these methods.

See the following documents for more recommendations on how to structure source code:

• Doug Lea's Draft Java Coding Standard
• Seven tips on writing clean code