------
 Committers - JIRA Conventions
 ------
 Apache Onami Documentation Team
 ------
 2012-11-16
 ------

~~
~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~   http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.
~~

Code Style And Code Conventions

 This document describes how developers and contributors should write code. The reasoning of these styles and conventions is
 mainly for consistency, readability and maintainability reasons.

* Generic Code Style And Convention

 All working files (java, xml, others) should respect the following conventions:

 * <<License Header>>: Always add the current {{{http://www.apache.org/legal/src-headers.html#headers}ASF license header}}
 in all versioned files. A {{{https://svn.apache.org/repos/asf/onami/committers/LICENSE-header}file}} on SVN
 contains a header template for different formats.

 * <<Trailing Whitespaces>>: Remove all trailing whitespaces. If your are an Eclipse user, you could use the
 {{{http://andrei.gmxhome.de/anyedit/}Anyedit Eclipse Plugin}}.

~~ * Using SVN properties like \$Id: \$ => Is it a wanted goal for all files like java or apt?
 []

 and the following style:

 * <<Indentation>>: <<Never>> use tabs!

 * <<Line wrapping>>: Always use a 120-column line width.

 []

 <<Note>>: The specific styles and conventions, listed in the next sections, could override these generic rules.

* {Java}

** {Java Code Style}

 The recommended style - adopted in the bigger part of the existing components, but optional - for Java is mainly:

 * <<White space>>: One space after control statements and between arguments (i.e. <<<if ( foo )>>> instead of
   <<<if(foo)>>>), <<<myFunc( foo, bar, baz )>>> instead of <<<myFunc(foo,bar,baz)>>>).
   No spaces after methods names (i.e. <<<void myMethod(), myMethod( "foo" )>>>)

 * <<Indentation>>: Always use 4 space indents and <<never>> use tabs!

 * <<Blocks>>: Always enclose with a new line brace.

 * <<Line wrapping>>: Always use a 120-column line width for Java code and Javadoc.

 * <<Readingness>>: Specify code grouping members, if needed. For instance in a Mojo class, you could have:

+-----+
package org.apache.onami.{component}

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *  http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

public abstract class QuartzModule
    extends AbstractModule
{

    // ----------------------------------------------------------------------
    // Static methods
    // ----------------------------------------------------------------------
    ...

    // ----------------------------------------------------------------------
    // class members
    // ----------------------------------------------------------------------

    /**
     * Describe here...
     */
    private Multibinder<JobListener> jobListeners;

    ...

    // ----------------------------------------------------------------------
    // Public methods
    // ----------------------------------------------------------------------

    ...

    // ----------------------------------------------------------------------
    // Protected methods
    // ----------------------------------------------------------------------

    /**
     * {@inheritDoc}
     */
    @Override
    protected final void configure()
    {
        ...
    }

    // ----------------------------------------------------------------------
    // Private methods
    // ----------------------------------------------------------------------
    ...

}
+-----+

 []

 The following sections show how to set up the code style in IDEA and Eclipse.
 It is strongly preferred that patches use this style before they are applied.

*** IntelliJ IDEA 4.5+

 Download <<<{{{https://svn.apache.org/repos/asf/onami/committers/intellij/onami-idea-codestyle.xml}onami-idea-codestyle.xml}}>>> and copy it to
 <<<~/.IntelliJIDEA/config/codestyles>>> then restart IDEA. On Windows, try
 <<<C:\Documents and Settings\<username>\.IntelliJIDEA\config\codestyles>>>

 After this, restart IDEA and open the settings to select the new code style.

*** Eclipse 3.2+

 Download <<<{{{https://svn.apache.org/repos/asf/onami/committers/eclipse/onami-eclipse-codestyle.xml}onami-eclipse-codestyle.xml}}>>>.

 After this, select Window \> Preferences, and open up the configuration for Java \> Code
 Style \> Code Formatter. Click on the button labeled Import... and select the file you
 downloaded. Give the style a name, and click OK.

** {Java Code Convention}

 For consistency reasons, our Java code convention is mainly:

 * <<Naming>>: Constants (i.e. static final members) values should always be in upper case.
   Using short, descriptive names for classes and methods.

 * <<Organization>>: Avoid using a lot of public inner classes. Prefer interfaces instead of default implementation.

 * <<Modifier>>: Avoid using final modifier on all member variables and arguments.
 Prefer using private or protected member instead of public member.

 * <<Exceptions>>: Throw meaningful exceptions to makes debugging and testing more easy.

 * <<Documentation>>: Document public interfaces well, i.e. all non-trivial public and
 protected functions should include Javadoc that indicates what it does.
 <<Note>>: it is an ongoing convention for the Maven Team.

 * <<Testing>>: All non-trivial public classes should include corresponding unit or IT tests.

 []

** {JavaDoc Convention}

 TO BE DISCUSSED

* {XML}

** {XML Code Style}

 The Maven style for XML files is mainly:

 * <<Indentation>>: Always use 2 space indents, unless you're wrapping a new XML tags line in which case you should
   indent 4 spaces.

 * <<Line Breaks>>: Always use a new line with indentation for complex XML types and no line break for simple XML
 types. Always use a new line to separate XML sections or blocks, for instance:

+-----+
<aTag>
  <simpleType>This is a simple type</simpleType>

  <complexType>
    <simpleType>This is a complex type</simpleType>
  </complexType>
</aTag>
+-----+

  In some cases, adding comments could improve the readability of blocks, for instance:

+-----+
<!-- Simple XML documentation -->
+-----+

  or

+-----+
<!--
 | This
 | is
 | a
 | block
 | documentation
-->
+-----+

 []

** {Generic XML Code Convention}

 No generic code convention exists yet for XML files.

** {POM Code Convention}

 The Maven team has {{{http://www.nabble.com/-Proposal--Pom-Code-Style-(WAS-svn-commit%3A-r670264----maven-plugins-trunk-maven-site-plugin-pom.xml)-td18083228.html}voted}}
 during the end of June 2008 to follow a specific POM convention to ordering POM elements.
 The consequence of this vote is that the {{{http://maven.apache.org/ref/current/maven-model/maven.html}Maven project descriptor}}
 is <<no more>> considered as the reference for the ordering.

 The following is the recommended ordering for all Maven POM files:

+-----+
<?xml version="1.0" encoding="UTF-8"?>
<!--
 | Licensed to the Apache Software Foundation (ASF) under one or more
 | contributor license agreements.  See the NOTICE file distributed with
 | this work for additional information regarding copyright ownership.
 | The ASF licenses this file to You under the Apache License, Version 2.0
 | (the "License"); you may not use this file except in compliance with
 | the License.  You may obtain a copy of the License at
 |
 |  http://www.apache.org/licenses/LICENSE-2.0
 |
 | Unless required by applicable law or agreed to in writing, software
 | distributed under the License is distributed on an "AS IS" BASIS,
 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 | See the License for the specific language governing permissions and
 | limitations under the License.
-->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

  <modelVersion>4.0.0</modelVersion>

  <parent>
    <groupId>org.apache.onami</groupId>
    <artifactId>onami-parent</artifactId>
    <version>{parent.version}</version>
  </parent>

  <groupId>org.apache.onami</groupId>
  <artifactId>onami-{component}</artifactId>
  <version/>
  <packaging/>

  <name>Apache Onami-{component}</name>
  <description>Apache Onami-{component} is a tool that ...</description>
  <url/>
  <inceptionYear/>

  <contributors/>

  <prerequisites/>

  <modules/>

  <scm/>
  <issueManagement/>
  <ciManagement/>
  <distributionManagement/>

  <properties/>

  <dependencyManagement/>
  <dependencies/>

  <build/>

  <reporting/>

  <profiles/>
</project>
+-----+

 <<Comments>>:

    [[1]] The <<<\<project/\>>>> element is always on one line.

    [[2]] The blocks are voluntary separated by a new line to improve the readingness.

    [[3]] The dependencies in <<<\<dependencies /\>>>> and <<<\<dependencyManagement /\>>>> tags have no specific ordering. Developers
    are free to choose the ordering, but grouping dependencies by topics (like groupId i.e. <<<org.apache.onami>>>) is a good practice.

    []

** {XDOC Code Convention}

 For consistency and readability reasons, XDOC files should respect:

 * <<Metadata>>: Always specify metadata in the <<<\<properties /\>>>> tag.

 * <<Sections>>: Always use a new line with indentation for <<<\<section /\>>>> tags.

 []

** {FML Code Convention}

 For readability reasons, FML files should respect:

 * <<FAQ>>: Always use a new line with indentation for <<<\<faq /\>>>> tags.

 []

~~ * {APT} Do we need any specific APT style/convention?