Guidelines

Java Code

In general, refer to http://en.wikipedia.org/wiki/The_Elements_of_Java_Style , make sure you understand and apply http://en.wikipedia.org/wiki/SOLID_(object-oriented_design).

• Always implement against interfaces, never concrete types.
• Write short classes: 100 lines is good, 200 lines is long, and everything beyond should be split up
• Avoid deep nesting levels
• Avoid if-else constructs, consider breaking up into smaller classes or guardians.
• Exception handling:
  • Extend java.lang.RuntimeException. Unchecked exceptions are much easier to handle and organize. Make all exceptions inherit ObjectMapperException.
  • Use the throws keyword only if you want to indicate a specific exceptions. It is not necessary as all exceptions should be unchecked ones. Do not use throws to add a generic exception to everything. This won't add any value.
  • Make sure you either handle or rethrow exceptions. If you rethrow, try to add more useful information.
• Write comments. If you add a class or an interface, at least add a line saying what problem this class solves, even if it's absolutely clear to you.
  • Use JavaDoc style comments before classes, fields and methods
  • Use double slash comments for inline comments
  • Don't comment the obvious.
  • Write comments that explain what the caller will get returned and what error conditions he can run into.
• Make use of Java 5 for loops. Really. They're easier to read and understand.
• Format your code, use the supplied eclipse formatter settings.
• Organize your imports

Files

• Files should be UTF-8 encoded with Unix linebreaks.
• Adhere to the formatting rules, for Eclipse there's a ready to use formatter file in the ide/ directory.
• Adhere to the Maven directory layout:
  • Java classes src/main/java
  • Tests go under src/test/java and mirror the directory structure of the code they test

API

• Do not touch the API in core/api unless you have a really good reason for it.
• Everything in core/api is independent of the actual persistence backends. Never ever add dependencies to concrete persistence subsystems.
• For every API level method add documentation what the method does, what it expects and what the outcome is. Remember, the API is what external developers will be using, and they won't know the internas.
• Be considerate with external dependencies. Be aware of transitive dependencies. We're building a library and we don't want to invade projects with a whole host of dependencies.