Guidelines

The development process follows some of the agile methods principles :

  • think before doing anything (write tech peaks docs)
  • keep it small and simple
  • test everything that could possibly break
  • write tests before code (or at least at the same time)

Header format

File

Every file header must be formated the same way and must contain the following information :

  • license
  • cvs $Id tag

Here is a template :



/**

* Redistribution and use in source and binary forms, with or without

* modification, are permitted provided that the following conditions are

* met :

*

* . Redistributions of source code must retain the above copyright

* notice, this list of conditions and the following disclaimer.

*

* . Redistributions in binary form must reproduce the above copyright

* notice, this list of conditions and the following disclaimer in the

* documentation and/or other materials provided with the distribution.

*

* . The name of the author may not be used to endorse or promote products

* derived from this software without specific prior written permission.

*

* THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR

* IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED

* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

* DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,

* INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES

* (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR

* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,

* STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN

* ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE

* POSSIBILITY OF SUCH DAMAGE.

*

* $Id: guidelines.xml,v 1.1 2005/07/14 16:56:31 jeanlaurent Exp $

*/

Class

Every class header must be formated accordingly and contain the following information :

  • class documentation
  • author
  • version : $Revision and $Date cvs tags

The following is a template :



/**

* <CLASS DOCUMENTATION>

*

* @author <NAME>

* @version $Revision: 1.1 $ $Date: 2005/07/14 16:56:31 $

*/

Documentation

The Javadoc tool is used to generate API documentation.

Many usefull guidelines are described by Sun in How to Write Doc Comments for the Javadoc Tool.

Package

Every package must be documented accordingly (even before starting the first line of code).

A package.html file must be placed within each package directory as described by Sun in How to Write Doc Comments for the Javadoc Tool.

Package documentation files must use this template.

Class

The class documentation is contained in every class/interface header.

It starts with a sentence ending with a dot describing the purpose of the class (the class brief description) such as 'This class provides for...'.

The detailed description follows after a <p> separator on a single line.

The optional @see javadoc tags come next, separated from the detailed description by a new line.



The following is a template :



/**

* <CLASS BRIEF DESCRIPTION>.

* <p>

* <CLASS DETAILED DESCRIPTION>.

*

* @see <SOMETHING>

* @see <SOMETHING ELSE>

*

* @author <NAME>

* @version $Revision: 1.1 $ $Date: 2005/07/14 16:56:31 $

*/




The detailed description can contain any of the following html tags :

  • <a href="link.html">link description</a>
  • <br>
  • <ul> </ul> and <li> </li>
  • <b> </b>
  • <i> </i>

class and interface names within <code> </code> ? with @link ?

Method

Tests

JUnit + EasyMock => test driven dev

Code

Conventions

The code conventions mainly follow Sun Code Conventions for the Java Programming Language, with the following modifications :

  • every opening brace must be preceeded by a new line :

    GoodWrong
    if (condition)

    {

    ...

    }
    if (condition) {

    ...

    }
    public void doSomething()

    {

    ...

    }
    public void doSomething() {

    ...

    }


Import

Imported classes must be completly specified :



GoodWrong
import java.util.Vector;

import java.util.Enumeration;
import java.util.*;

Exception

Synchronization

Wrong parameters