1.1. Purpose of this document

This document describes how to write well-written Java source code files, so that they can be read by any developpers working on a development project.

2.1. General coding conventions

We follow the rules published by Sun Microsystems. Please start by carefully reading the entire document from here before proceeding to the next section !

2.2. Particular coding conventions

To those general rules, we add the following one: all class variables starts with the underscore character '_'.

Also, it is important to respect some rules regarding the declaration of 'import', class variables and constants and method variables:

1. the source code of all classes should start with the following comment line:

       /* $Id: manual.xml,v 1.1 2005/10/12 15:01:23 pdurand Exp $ */
       

   This is a CVS keyword that will be replaced by CVS itself when the source file is committed to the CVS server. $Id: manual.xml,v 1.1 2005/10/12 15:01:23 pdurand Exp $ is then replaced by a standard header containing the name of the RCS file, the revision number, the date (UTC), the author, the state, and the locker (if locked).

   Here is a good class starter:

       /* $Id: manual.xml,v 1.1 2005/10/12 15:01:23 pdurand Exp $ */                  /* the CVS keyword Id*/
       package my.package;         /* the package declaration*/
   
       import javax.swing.JLabel;  /* an import declaration */
   
       public class MyClass {      /* the class declaration */
           ...
       }
       

2. only declare used classes instead of declaring a set of classes:

       import javax.swing.*;       /* AVOID ! */
   
       import javax.swing.JLabel;  /* GOOD ! */
       

3. class variables and constants have to be declared at the beginning of the class declaration. Also, group the declarations:

       public class MyClass {
           
           // declarations of class variables and constants
           private String _aString2;
           private int    _anInt2;    /* GOOD: a group of private class variables */
   
           public String _aString;
           public int    _anInt;      /* GOOD: a group of public class variables */
           
           public static final String A_CONSTANT = "toto";
           public static final int    TOTO = 1;
                                       /* GOOD: a group of public class constants */
   
           // declaration of constructor 
           public MyClass(){
               ...
           }
           
           // declaration of class methods
           public void myMethod1(){
               ...
           }
           
           private int _i;       /* AVOID this declaration here, between two methods */
                                 /* this declaration has to be put above, along
                                    with other private class variables */
           public void myMethod2(){
               ...
           }
       }
       

4. methods variables have to be declared at the beginning of the method declaration:

       public void myMethod1(){    /* GOOD example */
           int    i;
           String str;
       
           for (i=0;...){
               ...
           }
       }
       public void myMethod2(){  /* BAD example */
           String str;
       
           for (int i=0;...){    /* AVOID this declaration here */
               ...
           }
       }
       

Do not forget to document the entire code. Add JavaDoc for class headers, class variables/constants and method headers. Within the methods, add standard Java comments using either '//' (one-line comment) or '/**/' (multi-lines comment).

Here is a snapshot of a good example (you may use it to start a new source code):

/*$Id: manual.xml,v 1.1 2005/10/12 15:01:23 pdurand Exp $*/
package my.package;

import javax.swing.JFrame ;

/**
 * Type javadoc of class MyClass here.
 *
 * @author Patrick Durand, IRISA-INRIA
 *
 * @since Feb 11, 2005
 */
public class MyClass extends JFrame{

    /** type javadoc here */
    private String _aString2;

    /** type javadoc here */
    public static final String A_CONSTANT = "toto";

    /**
     * type javadoc for MyClass constructor here
     */
    public MyClass(){
        ...
    }

    /**
     * type javadoc fo MyClass constructor here
     */
    public void myMethod1(){
        ...
    }
}