content/apt/developers/conventions/code.apt

 ------
 Maven Code Style And Code Conventions
 ------
 Vincent Siveton
 ------
 2008-07-05
 ------

~~ 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.

~~ NOTE: For help with the syntax of this file, see:
~~ http://maven.apache.org/doxia/references/apt-format.html

Maven 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 versionned files.

 * <<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 Maven style 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:

+-----+
public class MyMojo
{
    // ----------------------------------------------------------------------
    // Mojo components
    // ----------------------------------------------------------------------

    /**
     * Artifact factory.
     *
     * @component
     */
    private ArtifactFactory artifactFactory;

    ...

    // ----------------------------------------------------------------------
    // Mojo parameters
    // ----------------------------------------------------------------------

    /**
     * The POM.
     *
     * @parameter expression="${project}"
     * @required
     */
    private MavenProject project;

    ...

    // ----------------------------------------------------------------------
    // Mojo options
    // ----------------------------------------------------------------------
    ...

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

    /**
     * {@inheritDoc}
     */
    public void execute()
        throws MojoExecutionException
    {
      ...
    }

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

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

    // ----------------------------------------------------------------------
    // Static methods
    // ----------------------------------------------------------------------
    ...
}
+-----+

 []

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

*** IntelliJ IDEA 4.5+

 Download <<<{{{../../developers/maven-idea-codestyle.xml}maven-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 <<<{{{../../developers/maven-eclipse-codestyle.xml}maven-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

+-----+
    <!-- ====================================================================== -->
    <!-- Block documentation                                                    -->
    <!-- ====================================================================== -->
+-----+

 []

** {Generic XML Code Convention}

 No generic code convention exists yet for XML files.

** {POM Code Convention}

 The team has {{{http://maven.40175.n5.nabble.com/Proposal-Pom-Code-Style-WAS-svn-commit-r670264-maven-plugins-trunk-maven-site-plugin-pom-xml-td210642.html#a210643}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:

+-----+
<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/xsd/maven-4.0.0.xsd">
  <modelVersion/>

  <parent/>

  <groupId/>
  <artifactId/>
  <version/>
  <packaging/>

  <name/>
  <description/>
  <url/>
  <inceptionYear/>
  <organization/>
  <licenses/>

  <developers/>
  <contributors/>

  <mailingLists/>

  <prerequisites/>

  <modules/>

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

  <properties/>

  <dependencyManagement/>
  <dependencies/>

  <repositories/>
  <pluginRepositories/>

  <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.maven>>>) is a good practice.

    []

 <<Note>>: There existing two alternativs to change order of a pom file
 {{{http://www.mojohaus.org/tidy-maven-plugin/}Tidy Maven Plugin}} or the
 {{{https://github.com/Ekryd/sortpom}maven-sortpom-plugin}}. 

** {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?