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. The internal classes, must have the internal word in its 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.

Logging

1. In general logging is a good idea.
2. Use Commons Logging.
3. For debug messages, call if (log.isDebugEnabled()) prior to calling log.debug().

Formatting

1. In perfect world all people, who contribute code, use the same IDE with the same formatting preferences.
2. It should be a good idea to attach a formatter profile for Eclipse that we expect contributors to use.
3. 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

Building

Maven