Coding Guidelines

Coding Guidelines describe the guidelines of code contribution for the Contributors and Committers.
This is a living document and is still being discussed on the Wink mailing lists. Please feel free to discuss and modify the guidelines.

Coding

Backward Compatibility

  1. The project must keep backward compatibility between minor versions, unless the change is required to fix a bug.
  2. The project should keep backward compatibility between major versions, if possible.
  3. In order to reduce amount of potential backward compatibility problems, follow the following guidelines:
    1. Expose as few APIs as possible to user.
    2. Prefer exposing interfaces to exposing classes.
    3. An internal class, must have the internal word in its package name (e.g. org.apache.wink.internal)
    4. Remember: it's always possible to move a class from internal package outside, but it's never possible to move the classes to internal, after they were released.
    5. Classes that are exposed to user only by their class name (e.g. servlets, listeners, spring beans) should be located in the internal package. However, they must contain a javadoc clarification that their name must not be changed.

Potential Programming Problems

  1. Never call methods that can be overridden by a subclass from the constructor.
    1. If you call any method from the constructor, either declare the whole class final.
    2. Or make method private, or final, or static.
  2. Exceptions Handling
    1. Checked Exceptions
      1. Handle checked exceptions when possible.
      2. In case the exception cannot be handled, allow it to propagate to the calling method by declaring "throws".
      3. If the method's API cannot be changed, wrap the original exception with WebApplicationException. Important! Never wrap unchecked exceptions with WebApplicationException!
      4. The InvocationTargetException should always be handled. Consider using the following pattern: 
        try {

} catch (InvocationTargetException e) {
    Throwable targetException = e.getTargetException();
    if (targetException instanceof RuntimeException) {
        throw (RuntimeException) targetException;
    }
    throw new WebApplicationException(targetException);
}
    2. Unchecked Exceptions (Runtime Exceptions)
      1. Don't catch unchecked exceptions unless you can handle them properly.
      2. Be aware of "catch (Exception e)" statement, since it also catches unchecked exception. If there are multiple checked exceptions that should be handled in the same way, consider using the following pattern: 
        try {
    
} catch (RuntimeException e) {
    throw e;
} catch (Exception e) {
   // handle exception here
}

Logging

  1. In general logging is a good idea.
  2. Use Slf4j.
  3. For debug messages, call if (log.isDebugEnabled()) prior to calling log.debug().
  4. The following code is usually bad. There is no need to log exception and re-throw it: 
    try {
    
} catch (Exception e) {
    logger.error(e.getMessage(), e);
    throw new RuntimeException(e);
}
    Either log it, or re-throw.

Logging Messages

  1. Messages which are visible to the end user should have their strings externalized and read from a properties file to allow for easier NLS translation.
  2. Debug messages do not need to be put into a properties file.

Formatting

In a perfect world all people, who contribute code, use the same IDE with the same formatting preferences which, for example, significantly reduces a number of redundant SVN merges.

  1. An Eclipse code style is attached to this page: wink-eclipse-codestyle.xml Code contributions may use other format styles but please try to use at least the following rules.
  2. Anyway for people, who don't use Eclipse, or want to keep their formatting preferences, let's define some basic rules:
    1. Do not use Tab. For indentation use only spaces. Indentation size is 4 spaces.
    2. Maximum line width: 100 characters.

Spring

  1. All Spring bean names must start with "wink".
  2. Do not use dots in the bean names, since it may effect some spring functionality (e.g. util:property-path cannot be used with dots)
  3. Add "internal" to the bean names that should not be used by the user.
  4. When using PropertyPlaceholderConfigurer use the following guidelines:
    1. The "order" property should be set between 1 and Integer.MAX_VALUE. I would suggest setting it somewhere around Integer.MAX_VALUE/2 to ensure that anyone can insert a PropertyPlaceholderConfigurer both before and after.
    2. Set "ignoreUnresolvablePlaceholders" to true, to ensure that Wink won't fail because of others placeholders.
    3. Create a unit test, which will hold a validating PropertyPlaceholderConfigurer (ignoreUnresolvablePlaceholders=false) to ensure that none forgets to resolve a placeholder.
    4. All properties must start with "wink".

Building

Note: It's not yet decided if Ant or Maven or both will be used for building.

Maven

  1. All plugins/dependencies versions must appear only in the parent pom under the plugins/dependencies management. The examples (samples) may be exception to this rule, since they may contain additional dependencies.
  • No labels