View source for SMILA/Development Guidelines

This page covers a collection of development guidelines whose compliance should ensure that SMILA appears as a unified product rather than as a loose collection of parts worked on by a variety of individuals each with their own styles and ways of working. Furthermore it contains information on the used software components and requirements and provides descriptions (how-tos) of common tasks (e.g. setting up the development environment).

== How-to manuals ==
Find a list of How-To manuals at [[SMILA/HowTo|SMILA How-to manuals]].

== Development requirements ==

=== Java ===

The officially Java version needed for this project is Java 1.7.

=== Eclipse  ===

The official version is Eclipse 4.2, but you can also use Eclipse 3.7 or later.

== Development conventions ==

=== Description of make.xml ===
For a description of the build file <tt>make.xml</tt> refer to [[SMILA/Development_Guidelines/Introduction to make.xml|Introduction to make.xml]].

=== Continuous integration ===
Each developer should check his code before committing it to the repository regarding:
* Compilation errors
* Checkstyle (see [[#Checkstyle|Checkstyle]])
* Build process: Check if your bundles and your test bundles are fully integrated in the whole build process
*:(see [[SMILA/Development_Guidelines/How to integrate new bundle into build process|How to integrate new bundle into build process]] and [[SMILA/Development_Guidelines/How to integrate test bundle into build process|How to integrate test bundle into build process]])
* Tests: Run a local build with the <tt>build.xml</tt> to test all existing JUnit tests. 
*:(see [[SMILA/Development_Guidelines/Howto_build_a_SMILA-Distribution|How to build a SMILA distribution]] for the setup)
*: Be aware that running tests in Eclipse doesn't mean that they also run successful with the pde-build.

The failed JUnit tests are reported at the end of the build output.

Furthermore the full JUnit reports are generate under <tt>eclipse.build/reports/junit/</tt> and the
error messages from the JUnit reports are stored under <tt>eclipse.build/reports_errors_txt/</tt>.

Everyone should monitor the trunk at the build server and if there is a "red" build everyone should look if he has committed the error.

If the error could not be solved within the next build, the developer should inform the developer team that there is a problem with the build and that he is working on the solution.

=== File header & copyright notice ===
For guidelines on file header and copyright notices see [[SMILA/Project Guidelines|Project Guidelines]].

=== Eclipse code formatter profile ===

The Eclipse code formatter file is available in trunk at <tt>SMILA.builder/eclipse-formatter/Eclipse-formatter-Brox-3.2-3.3.xml</tt>.

To import the Eclipse code formatter profile:
# Select ''Window > Preferences'' in Eclipse and switch to the ''Java > Code Style > Formatter'' preferences page.
# Click the ''Import'' button and select the downloaded formatter file.

{{Note|formatter vs. save actions|most source files have been edited with the save action turned on: "remove trailing white spaces on all lines". If you dont have this set then formatting the whole file will result in a lot white space of changes, which is cumbersome as is clutters diffs and poses problems to patches. So please turn this feature on.}}

=== Checkstyle ===

Each Eclipse project (bundles) should follow the SMILA Coding Conventions. 

We use different checkstyle rules for "normal" bundles and test bundles. So there are two files containing the Checkstyle configurations in the trunk that you have to import (see below).

'''Eclipse checkstyle plugin'''

The eclipse-cs Checkstyle plugin integrates the source code analyzer Checkstyle into Eclipse IDE. By using this plugin your code is constantly inspected for problems. Within the Eclipse workbench you are notified of problems via the Eclipse ''Problems'' View and source code annotations just as you would see with compiler errors or warnings. The Checkstyle Eclipse plugin can be obtained from the update site: [http://eclipse-cs.sourceforge.net/update/ http://eclipse-cs.sourceforge.net/update/]. Instructions about how to set up the Checkstyle plugin for your project can be obtained from [http://eclipse-cs.sourceforge.net/basic_setup_project.html here]. 

'''Setup checkstyle configuration'''

# Click ''Window > Preferences'' in Eclipse.
# Select the ''Checkstyle'' preference page and click the ''New'' button. 
# Select ''External Configuration File'' as ''Type'' and point to the location of the file 
#: ''(if using checkstyle 4.x)''  <tt>SMILA.Builder/checkstyle/smila_checkstyle.xml</tt>.
#: ''(if using checkstyle 5.x - recommended)''  <tt>SMILA.Builder/checkstyle/smila_checkstyle-5.xml</tt>.
# This Checkstyle configuration profile should be named (while importing): <strong>"SMILA Checkstyle"</strong> and it should be set as ''default''.
# Select ''External Configuration File'' as ''Type'' and point to the location of the file 
#: ''(if using checkstyle 4.x)''  <tt>SMILA.Builder/checkstyle/smila-test_checkstyle.xml</tt>.
#: ''(if using checkstyle 5.x - recommended)'' <tt>SMILA.Builder/checkstyle/smila-test_checkstyle-5.xml</tt>.
# This Checkstyle configuration profile should be named (while importing): <strong>"SMILA Test Checkstyle"</strong>.

'''Warnings'''

Most checkstyle warnings will be self-explaining. But there are two metrics considering method complexity that should be pointed to here explicitly, in case you got appropriate warnings: 
:* [http://checkstyle.sourceforge.net/config_metrics.html  CyclomaticComplexity]
:* [http://checkstyle.sourceforge.net/config_metrics.html  NPathComplexity ]

=== Reduce javadoc overhead ===

Instead of writing member variable comments as
<source lang="java">
 /** 
 * switch to true to add newlines for better readability, but poorer performance. 
 */
 private final boolean _printPretty;
</source>

it's more readable and clearer to write such javadoc comments as one line:
<source lang="java">
 /** switch to true to add newlines for better readability, but poorer performance. */
 private final boolean _printPretty;
</source>

=== Creation of bundles ===
For information on creating and integrating bundles refer to the following pages:

* [[SMILA/Development_Guidelines/Create a bundle (plug-in)|Create a bundle (plug-in)]]
* [[SMILA/Development_Guidelines/How to integrate new bundle into build process|How to integrate a new bundle into the build process]]
* [[SMILA/Development_Guidelines/How to integrate test bundle into build process|How to integrate a test bundle into the build process]]
* [[SMILA/Development_Guidelines/3rd party bundle|How to add 3rd party bundle]]

=== Naming conventions for launch files (.launch) ===

It is a good thing to share your launches and many do so already which helps greatly to run tests quickly from within Eclipse. However, in order that at least I don't get confused, we need to define a naming scheme for the <tt>.launch</tt> files!

''' Preliminary convention: ''' <tt><bundle name>[_config name].launch</tt>

The <tt>[config name]</tt> part is optional and needed when several <tt>.launch</tt> files exist for the same bundle but with different settings.

=== Generated source code goes into code/gen source folder (like Jaxb) ===

All generated source code (eg. JAXB) goes into the distinct source code folder code/gen.
Where possible all generated classes should also have their own package.
Reasons:
* Separate generated source code from handwritten code
* Easier filtering for Checkstyle
(see [[SMILA/Development_Guidelines/Setup for JAXB code generation|Setup for JAXB code generation]] for details specific to creating crawler configurations.)

=== Logging guidelines ===

In SMILA apache commons logging is used with log4j. The log4j.properties are located in SMILA.application. Here are some guidelines how and when logging should be used:
* use local Log instances in each class where you want to log:
<source lang="Java">
private final Log _log = LogFactory.getLog(MyClass.class);
</source>
* always check log level before logging 'debug' and 'info', e.g. 
<source lang="Java">
if (_log.isDebugEnabled()) {
    _log.debug("Your debug message", e);
}
</source>
For 'warn' and 'error' messages the log level check can be omitted.

* do '''not''' log exceptions before throwing new exceptions, e.g.
<source lang="Java">
...
if( paramXY == null ) {
    if (_log.isErrorEnabled()) {
        _log.error("paramXY is not set");
    }
    throw new NullPointerException("paramXY is not set");
}
</source>

'''When to use what log level and what information to provide?'''

{| class="wikitable"
|-
! FATAL
| designates very severe error events that will presumably lead the application to abort.
|-
! ERROR
| designates error events that might still allow the application to continue running. 
|-
! WARN
| designates potentially harmful situations. 
|-
! INFO
| for the "high level" information. For example - interesting runtime events (startup/shutdown). 
|-
! DEBUG
| only for the software developer interesting messages (detailed information on the flow through the system).
|-
|}

A good resource on how to use the levels in regard to the ''Enterprise'' context offers [http://commons.apache.org/logging/guide.html#JCL%20Best%20Practices JCL Best Practices].

== Used technologies ==

=== OSGi related information ===

* [[SMILA/Development Guidelines/Declarative Services|Declarative services]]

[[Category:SMILA]]