<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:mml="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook"
         xml:id="developerguide.code_convention">
  <info>
    <title>Code Conventions in JOnAS</title>
  </info>

  <para>Contributions should follow the JOnAS code convention. A good document
    to begin with is 
    <link xlink:href="http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html">Java
      code convention</link>. Other conventions are also listed in this
    document.</para>

  <para>In addition, JOnAS uses tools to check the compliance: the 
    <link xlink:href="http://checkstyle.sourceforge.net/">checkstyle plugin</link> and
    the <link xlink:href="http://eclipse-cs.sourceforge.net/">eclipse checkstyle
      plugin</link>. The configuration settings are available on 
    <link xlink:href="http://forge.objectweb.org/plugins/scmsvn/index.php?group_id=5">JOnAS
      SVN</link>.</para>

  <section>
    <info>
      <title>File Organization</title>
    </info>

    <section>
      <info>
        <title>Header</title>
      </info>

      <para>All files should have a header that contains the LGPL and the
        date.</para>

      <para>If a file is modified, the modification year should be appended to
        the existing year, which is the year it was initially created. For
        example, if the create date is '1999' or '2004' it should be edited to
        '1999-2006' or '2004-2006', respectively.</para>

      <para>Also, the tag $Id: code_convention.xml 314 2006-04-04 09:39:43Z
        pinheirg $ should be added. The following is a header example:</para>

      <para><programlisting>
/**
 * JOnAS: Java(TM) Open Application Server
 * Copyright (C) 1999-2009 Bull S.A.S.
 * Contact: jonas-team@ow2.org
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
 * USA
 *
 * Initial developer(s):
 * --------------------------------------------------------------------------
 * $Id:code_convention.xml 13113 2008-03-11 10:58:50Z eyindanga $
 * --------------------------------------------------------------------------
 */
      </programlisting></para>
    </section>

    <section>
      <info>
        <title>Imports</title>
      </info>

      <para>Imports should reference a valid class name, instead of using
        wildcard imports. Wildcard imports are not authorized.</para>

      <para>For example, if the interface and class List and ArrayList are
        used, the imports should not be as follows:</para>

      <para><programlisting>
import java.util.*;
      </programlisting></para>

      <para>The imports should have each class as follow:</para>

      <para><programlisting>
import java.util.List; 
import java.util.ArrayList;
      </programlisting></para>

      <para>The classes should not have an unused import.</para>

      <note>
        <para>The Eclipse IDE provides facilities to do this job. There is the
          option Organize Imports (<command>Shift+Ctrl+O</command>) in the menu
          Source that correctly inserts the imports and removes the unused
          imports. However, this option does not work well with 'import
          static'.</para>
      </note>
    </section>

    <section>
      <info>
        <title>Class and Interface Declarations</title>
      </info>

      <para>The class and interface names should begin with an uppercase
        letter. Also, each class and interface has an @author tag in the
        comment. For example:</para>

      <para><programlisting>
/**
 * This is an example that shows a class/interface declaration.
 * @author Loris Bouzonnet
 * @author Stephane Zeng
 */
public class ClassExample implements InterfaceExample {
}
      </programlisting></para>
    </section>
  </section>

  <section>
    <info>
      <title>Indentation / whitespace</title>
    </info>

    <section>
      <info>
        <title>Indentation</title>
      </info>

      <para>The space character is used instead of the tab character. The
        number of spaces for an indent is <emphasis>4 spaces</emphasis>.</para>

      <para>Wrapping a single source line into multiple lines should follow
        the <link
               xlink:href="http://java.sun.com/docs/codeconv/html/CodeConventions.doc3.html#248">Java
          code convention</link>.</para>
    </section>

    <section>
      <info>
        <title>whitespace</title>
      </info>

      <para>Any trailing spaces should be removed. Eclipse provides a plugin
        that removes the trailing spaces and converts the tab into spaces. The
        plugin is <link
                     xlink:href="http://andrei.gmxhome.de/anyedit/">AnyEdit</link>.</para>

      <para>Use whitespaces in for() loop, while(), when concatenating
        strings. One space should be added before the operator and another after
        the operator. For example, the correct syntax is:</para>

      <para><programlisting>
for (int i = 0; i &lt; arTest.length; i++) {
    String strResult = "The element " + i + " has the value " + arTest[i];
}
      </programlisting></para>

      <para>The following code does not adhere to the convention:</para>

      <para><programlisting> 
for (int i = 0; i&lt; arTest.length; i++) {
    String strResult = "The element "+ i+" has the value "+arTest[i];
}
      </programlisting></para>
    </section>
  </section>

  <section>
    <info>
      <title>JavaDoc Comments</title>
    </info>

    <para>All methods and attributes (including protected and private) must
      have a comment. The parameters, the exceptions thrown, and the method
      return should have a comment in the method comment. For example:</para>

    <para><programlisting>
/**
 * This is an example that is used in the JOnAS Code Convention.
 */
private int intValue;

/**
 * This is an example method to show a class comment.
 * @param a an example of parameter.
 * @param b other example of parameter.
 * @return the method result.
 * @throws Exception the exception thrown by the method.
 */
public int add(final int a, final int b) throws Exception {
    return a + b;
}
    </programlisting></para>
  </section>

  <section>
    <info>
      <title>Statements</title>
    </info>

    <section>
      <info>
        <title>If/else</title>
      </info>

      <para>Braces must be used in the if/else blocks, even if there is a
        single statement. To illustrate:</para>

      <para><programlisting>
if (true) {
    doThis();
}
      </programlisting></para>

      <para>The following is not allowed:</para>

      <para><programlisting> 
if (true)
    doThis();
      </programlisting></para>

      <para>The position of the braces should be the same as in the first
        example. The following format is incorrect:</para>

      <para><programlisting>
if (true)
{
    test1();
    test2();
}
      </programlisting></para>
    </section>

    <section>
      <info>
        <title>Try/catch</title>
      </info>

      <para>All exceptions require a statement; no silent catching is allowed.
        For example:</para>

      <para><programlisting>
try {
    doThis();
} catch (Exception e) {
    // should not occur
}
      </programlisting></para>

      <para>A logger can be used:</para>

      <para><programlisting>
try {
    doThis();
} catch (Exception e) {
    logger.logDebug("Exception while doing .....", e);
}
      </programlisting></para>
    </section>

    <section>
      <info>
        <title>Naming Conventions</title>
      </info>

      <section>
        <info>
          <title>Static Final Attributes</title>
        </info>

        <para>Declarations are static final, not final static. This is a JLS
          recommendation.</para>
      </section>

      <section>
        <info>
          <title>Constants</title>
        </info>

        <para>Constants should be static and final, and should adhere to the
          following:</para>

        <para><programlisting>
'^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$'
        </programlisting></para>
      </section>

      <section>
        <info>
          <title>No Magic Numbers, Use Constants</title>
        </info>

        <para>Constants must be used in the code and magic number must be
          avoided. For example, the following is not allowed:</para>

        <para><programlisting>
private int myAttribute = 5;
</programlisting></para>

        <para>The correct format is:<programlisting>
/**
 * Default value
 */
private static final int DEFAULT_VALUE = 5;

/**
 * This attribute is initialized with the default value
 */
private int myAttribute = DEFAULT_VALUE;
        </programlisting></para>
      </section>

      <section>
        <info>
          <title>Attribute Name</title>
        </info>

        <para>The attribute name should not have an underscore ( _ ). The _ is
          valid for constants that are in uppercase.</para>

        <para>Use pValue and mValue instead of p_Value and m_Value.</para>

        <para>The pattern for attribute name is:</para>

        <para><programlisting>
'^[a-z][a-zA-Z0-9]*$'
</programlisting></para>
      </section>
    </section>
  </section>
</section>
