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:
~~ https://maven.apache.org/doxia/references/apt-format.html

Maven Code Style And Code Conventions

 This document describes how developers and contributors should format code 
 in order to improve consistency, readability and maintainability.

* Generic Code Style And Convention

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

 * <<License Header>>: Always add the current {{{https://www.apache.org/legal/src-headers.html#headers}ASF license header}}
 in all files checked into the source code repository.

 * <<Trailing Whitespace>>: Remove all trailing whitespace. If you use
 Eclipse, you can 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, can 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 (e.g. <<<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) should always be in upper case.
   Use short, descriptive names for classes and methods.

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

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

 * <<Exceptions>>: Throw meaningful exceptions to make debugging and testing easier.

 * <<Documentation>>: Document public interfaces well, i.e. all non-trivial public and
 protected functions should include Javadoc that indicates what they do.

 * <<Testing>>: All non-trivial public classes should corresponding unit or
 integration 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 {{{https://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 {{{https://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 https://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 exist two alternatives to change order of a pom file
 {{{https://www.mojohaus.org/tidy-maven-plugin/}Tidy Maven Plugin}} or the
 {{{https://github.com/Ekryd/sortpom}Sortpom Maven 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?