Commenting Example


Main Class File Header

This is what I put at the top of HW1.java, the main class (i.e. that had the public static void main(String[] args) method in it). It's a summary of what's in my project and when I finished it. You should include this format whenever you go to write programs. 
/******************************* MAIN HEADER **********************************
 Title:           Machine Learning (CS760) Homework #1

 Files:           CFeature.java, CValue.java, Classifier.java, DFeature.java,
                  DValue.java, DataIO.java, DataPoint.java, DataSet.java,
                  Feature.java, HW1.java, IO.java,List.java, NaiveBayes.java,
                  SortedList.java, SplitDataSet.java,Statistics.java,
                  Value.java, VoteCounter.java, kFoldDataSet.java,
                  kNearestNeighbor.java

 Author:          Mr. Schultz
 CS Login:        mschultz
 Collaborators:   none

 Due Date:        2/13/03
 Completion Date: 2/9/03

 Course:          CS760
 TA:              Jude Shavlik

 Compiler:        CodeWarrior IDE 5.0
 Platform:        Windows 2000
**************************** 80 columns wide *********************************/

Source Class File Header

This is what I put at the top of CFeature.java, one of the source files in my machine learning homework 1 project. This should go at the top of all of your source files excepting the main class. I have a similar header, but with appropriate changes, for CValue.java, Classifier.java, etc. 
/******************************* FILE HEADER **********************************
 Main Class File: HW1.java
 File:            CFeature.java

 Author:          Mr. Schultz
 CS Login:        mschultz
 Collaborators:   none

 Completion Date: 2/6/03

 Course:          CS760
 TA:              Jude Shavlik

 Compiler:        CodeWarrior IDE 5.0
 Platform:        Windows 2000
**************************** 80 columns wide *********************************/

Javadocs

Class Headers
Class Headers are used to tell the reader what the role of the class is in the program. Every class that you write. In addition to a File Header, (which tells which program the class is a part of and when it was made) you must always include a Class Header for every class that you write, including the main class. (In that case, you'll give a short synopsis of the program). Here is the class header for CFeature.java. 
/** CFeature is used to represent some continuous-valued property, or
  * feature, of some data point. For example, XY Points have two
  * CFeature objects: a CFeature for the possible x values and a
  * CFeature for the possible y values.
  *
  * Bugs: none known
  *
  * @author Mr. Schultz
  */
Method Header
Method Headers describe the role of a method, specifying parameters and return values. Every method, including constructors, should have a method header. Note that there may be several parameters, or no parameters. There also may or may not be a return value. Here is a method header for the method isValue() of CFeature. 
    /** Takes in a value as a parameter and return a boolean for whether or not the value is
      * acceptable for (within the range of) the CFeature object.
      * 
      * @param value   the value to be tested
      * 
      * @return        true if the value is between the CFeature's min and max
      */
Data Member
Data must also be commented to explain their roles. Here's my comment for min and max in CFeature. 
    /** The minimum allowed value for this continuous feature */
    private double min;

    /** The maximum allowed value for this continuous feature */
    private double max;

Example Documented Class

Here is the whole CFeature class. Don't be too concerned if you don't understand what everything means. This is primarily an exercise in learning proper commenting techniques. However, I will be happy to entertain any questions about this class.

Notice that most of the file is comments and not code. That's fine. In fact, don't be surprised if properly wirting all of the comments takes almost as long to wirte as some of the shorter methods. Just like in any class, presentation counts. Your readers need to know what's going on. 
/******************************* FILE HEADER **********************************
 Main Class File: HW1.java
 File:            CFeature.java

 Author:          Mr. Schultz
 CS Login:        mschultz
 Collaborators:   none

 Completion Date: 2/6/03

 Course:          CS760
 TA:              Jude Shavlik

 Compiler:        CodeWarrior IDE 5.0
 Platform:        Windows 2000
**************************** 80 columns wide *********************************/

/** CFeature is used to represent some continuous-valued property, or
  * feature, of some data point. For example, XY Points have two
  * CFeature objects: a CFeature for the possible x values and a
  * CFeature for the possible y values.
  *
  * Bugs: none known
  *
  * @author Mr. Schultz
  */

public class CFeature extends Feature {

    /** The minimum allowed value for this continuous feature */
    private double min;

    /** The maximum allowed value for this continuous feature */
    private double max;

    /** Constructs a CFeature object with the specified feature number
      *
      * @param number    the identification number of this feature
      */
    public CFeature(int number) {
        super(number);
        type = CONTINUOUS;
    }

    /** Constructs a CFeature object with the specified feature number,
      * minimum allowed value and maximum allowed value.
      *
      * @param number    the identification number of this feature
      * @param min       the minimum allowed value for this feature
      * @param max       the maximum allowed value for this feature
      */
    public CFeature(int number, double min, double max) {
        this(number);
        setMin(min);
        setMax(max);
    }

    /** Constructs a CFeature object with the specified feature number,
      * minimum allowed value and maximum allowed value.
      *
      * @param name      the name of this feature
      * @param number    the identification number of this feature
      * @param min       the minimum allowed value for this feature
      * @param max       the maximum allowed value for this feature
      */
    public CFeature(String name, int number, double min, double max) {
       this(number,min,max);
       setName(name);
    }

    /** sets the minimum allowed value of the feature to the specified
      * number.
      *
      * @param min       the new minimum allowed value for this feature
      */
    public void setMin(double min) {
        this.min = min;
    }

    /** sets the maximum allowed value of the feature to the specified
      * number.
      *
      * @param max       the new maximum allowed value for this feature
      */
    public void setMax(double max) {
        this.max = max;
    }

    /** returns the minimum allowed value for this feature
      *
      * @return          the minimum allowed value
      */
    public double getMin() {
        return min;
    }

    /** returns the maximum allowed value for this feature
      *
      * @return          the maximum allowed value
      */
    public double getMax() {
        return max;
    }

    /** Takes in a value as a parameter and return a boolean for whether or not
      * the value is acceptable for (within the range of) the CFeature object.
      * 
      * @param value   the value to be tested
      * 
      * @return        true if the value is between the CFeature's min and max,
      *                and false otherwise
      */
    public boolean isValue(double value) {
        return min <= value && value <= max;
    }

}