The development process follows some of the agile methods principles :
Every file header must be formated the same way and must contain the following information :
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 $
*/
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.
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.
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 :
class and interface names within <code> </code> ? with @link ?
The code conventions mainly follow Sun Code Conventions for the Java Programming Language, with the following modifications :
Good | Wrong |
---|---|
if (condition)
| if (condition) {
|
public void doSomething()
| public void doSomething() {
|