Developers Guide

Project Organization

Maven

Except for some platform-specific artifacts, for instance Eclipse plugins, project should follow Apache Maven's conventions.

All software dependencies should be correctly declared in the Project Object Model (pom.xml file). Prefer use a dependencyManagement to manage the dependencies, and use properties to manage the dependencies version.

Package Organization

Keep together classes that implement a same feature. Organize packages by features, not by layers. Read this article for more information.

Avoid packages named beans, exceptions, factories, or collections.

Code Conventions

Except for the cases enumerated below, the Java source code should follow Google's Style Guide: https://google.github.io/styleguide/javaguide.html

Method Names

Part of the source code is meant to be specialized by automatically generated code. To avoid naming conflicts, classes that belong to the emf.ecore hierarchy should avoid standard Getter and Setter names.

For instance, access methods for an attribute named foo should be:

String foo();          // The Getter
void foo(String str);  // The Setter

Access methods from other classes should use standard names.

Each class must manage its own fields. Except for special cases, getters and setters must not return a mutable collection.

Preconditions

Use preconditions instead of assertions or comments for checking conditions that must always be true and invariants in method bodies.

public void foo(int i) {
  Preconditions.checkArgument(i > 0 && i <= 12, "Out of range");
  // Method code
}

Annotations (JSR-305)

Use JSR-305 annotations, such as @Nonnull, @Nullable, @ParametersAreNonnullByDefault, etc. These annotations are not processed at runtime, but are very useful for static code analysis.

Documentation

Every packages, classes, methods and fields should be properly documented.

The package documentation is located in main/javadoc, next to the main/java directory, and must only contains package-info.java files.

Software quality

Ideally, all methods should be tested in unit tests. For classes and methods related to data management, tests must also be created in the integration tests.

Design Tips

Supertypes should not depend on subtypes.

More precisely, an interface should not reference its implementation classes. For instance, the following code excerpt should be avoided:

public interface IFactory {
  IFactory eINSTANCE = FactoryImpl.init();
}