EclipsePlugin/DeveloperGuidelines

From DPFWiki

Jump to: navigation, search

Target platform: Eclipse Helios

As long as we don't use any native libraries except for those that come with Eclipse (SWT) we should be able to run on all architectures and os that eclipse itself runs on.

Contents

Coding and style conventions

First of all, for the auto-generated code we will not have any conventions but live with what the EMF code generator emits.

For code we write ourselves, please consult the following documents for style guidelines:

The one from geosoft is more readable, but all-in-all they say much the same. Note that there will probably be cases where breaking a rule makes for a better or more readable solution. Do not be afraid to break the rules, however do not do so either without a reason.

Refactoring

Refactoring EMF-models after the code is generated and been added to is not trivial. We need to make sure that the models are up-to-date so be careful when using the built-in features in eclipse for doing it. If a refactoring touches any visible features of the class (i.e. it affects something added through the model editing tools) the change needs to be implemented in the model first. As the code generator doesn't seem to know about things like renaming, the implementation of methods needs to be moved to the new skeleton method generated. Likewise, the old method needs to be deleted as since it's already marked as @generated NOT it won't be done automatically.

This said, refactoring is crucial to code health, so we just need to work with what tools we have and live with it.

Modeling

The domain model is created using EMF against the newest available EMF runtime in Helios. Use JavaSE-1.6 as the target platform for code generation. We use the modeling tools to generate the ecore-model, and not the java-to-ecore converter.

Naming conventions

Since this is an Eclipse plug-in project, we will try to follow Eclipse naming conventions.

We try to stay close to the conventions at http://wiki.eclipse.org/index.php/Naming_Conventions, but since we're not an Eclipse project, we don't use the org.eclipse namespace.

Our top-level package is no.hib.dpf, all the code we create should be inside this namespace. There are two "special" namespaces here, .feature and .pdebuild. These are projects that does not contain code, bur are used in the building process.

The first level after no.hib.dpf should signify the component of the plugin. (Component here is a loose term encompassing a logical part of the whole plugin. Eg. the metamodel is one component, the UI for the predicate designer may be another.) Each component is a seperate plug-in project.

Inside a component code is seperated in packages as is the norm in the java world. Please refer to the packaging chapters in the MOD251 (TODO: look up the name and chapters) book for guidelines on this.

In the interest of not exposing more of our internals that we would like, use the interal-setting on packages containing classes that does not form part of your public API. These packages should be in a namespace containing the element .internal., e.g. no.hib.dpf.gui.internal.frobnik. For EMF-generated code this means that we should consider putting .impl. inside an .internal. package.

Tests should have the part .tests. somewhere in the namespace name. Tests generated by EMF follow this convention if you don't change it on the generator model.

Extension points

When you design your code, consider extensibility. If something should be extensible, follow the Open-Closed principle and use polymorphism. Also, if the is a point where other authors should be able to add functionality, create an extension point out if it.

Document all extension points on the wiki.

Unit-testing

  • Don't test the auto-generated features of the code.
  • Do test the implementations of methods you define.
  • Testing of EMF-generated classes should be done with the EMF-generated test harness.
  • Unit test projects should be run by the PDE/Build process, please consult the build-dpf.xml-file in the project no.hib.dpf.pdebuild for instructions on how to make this happen.

Building

The packages are built on hudson on the no.hib.dpf-server. The project no.hib.dpf.pdebuild contains the main driver build scripts. When you add new component plugins, this has to be updated as it needs a list of all the names.

Personal tools