Title: Java Idioms

idiom name

reason for idiom

advantages of the idiom

disadvantages of the idiom

full description of the idiom including examples

javadoc comments

self documenting code. Permits the low level interface documentation to appear inline with the code. This prevents unnecessary duplication (i.e. separate document duplicating code comments).

low-level documentation for interface specifications should always be up to date.

slightly more time to produce the code (the combined code and interface specification time should be shorter). Must keep comments up to date with the source (maintenance issue).

There are certain points in a Java source file where javadoc comments may sensibly be placed. These are:

Note that one can profitably comment all forms of field or method specification (public, protected, private and package visibility). Running javadoc with an appropriate option will produce increasingly more detailed HTML documents. By default javadoc will generate documentation for the public and protected fields/methods.

Tags

The following table lists the javadoc tags and their possible placements:

Note that @since and @deprecated were introduced in JDK1.1.

The first period terminated sentence should be a short description of the class/interface, field or method. Watch out when including a decimal number! This will be used to generated a summary in the HTML documentation.

For trivial methods the short description along with a possible more complete description may be sufficient. This is especially true if the meanings of some parameters are obvious by their name or even by the method name. In non-trivial methods appropriate @param and @return (if non-void) should appear. Also if any exceptions are thrown then they should be documented with an @exception. One should use the fully qualified class name for the exception to permit the cross-reference documentation to be correctly generated.

Although it is unusual to include unchecked exceptions (e.g. those that extend java.lang.RuntimeException) in a method's throws clause it is good practice for the exceptions to be documented. For a good example of this see java.lang.String#charAt.

The idiom here is that classes, interfaces, fields and methods should be sensibly documented. Once one gets into the habit of typing in javadoc comments as one types the code it becomes second nature. Failure to do this loses out on one of Java's real strengths. An important point to note is that to be really useful the comments must be kept up to date.

In the Point example the constructor has commented the parameters. It wasn't really necessary as the constructor is trivial. In fact in setX commenting the parameter would be overkill. The @return in toString is for the benefit of the example.

Note that one can utilise the versioning from the source control system to give a possible entry for the @version tag.

/*
 *  Copyright  (c)  1998  Mark  Kuschnir
 */
package  com.xyz.graphics;
/**
  *  XY  coordinates  of  a  point  in  a  graphical  
  *  coordinate  system.
  *  Only  permit  points  in  the  positive  quadrant:  
  *    x  >=  0  and  y  >=  0.
  *  @author  Mark  Kuschnir
  *  @version  $Revision:  1.1$
  */
  
public  class  Point
{
        /**  X  coordinate.  */        
        private  double  x;
        /**  Y  coordinate.  */
        private  double  y;
        /**
          *  Construct  a  Point  object.
          *  @param  x  X  coordinate
          *  @param  y  Y  coordinate
          *  @exception  java.lang.IllegalArgumentException  
             if  x  <  0  or  y  <  0
          */
          public  Point(double  x,  double  y)
          {
                if  (x  <  0  ||  y  <  0)
                  throw  new  IllegalArgumentException
                              (x+"  <  0  ||  "+y+"  <  0");
                this.x  =  x;
                this.y  =  y;
          }
         /**
          *  Get  the  X  coordinate.
          */          
        public  double  getX()
        {
                return  (x);
        }        
        /**
          *  Set  the  X  coordinate.
          */          
        public  void  setX(double  x)
        {
                this.x  =  x;
        }        
        //  getY  +  setY  methods
         /**
          *  Return  string  representation  of  the  point.
          *  @return  string  representation
          */
        public  String  toString()
        {
              return ("("+x+","+y+")");
        }
    /**
     * Test the class.
     */     
    public static void main(String[] args)
    {
      try
      {
        Point p = new Point(1,2);
        System.out.println("point = "+p);
        p = new Point(-1,-2);
      }
      catch (Exception e)
      {
        e.printStackTrace();
      }
    }
}