5.3 Documentation With Comments

Now, we will learn one of the most useful features of Java: commenting and documentation. This allows us to write clear code and understand it. This will also allow readers to understand our code. With comments, we are explaining our code in easy to use words. These comments will not be compiled by the Java compiler.

Types of Comments and Their Uses

There are three types of comments, two which have the same purpose and one that has a more specific use.

Single-Line and Multi-Line Comments

Single-line comments are comments that are on one line while multi-line comments (also called block comments) are comments that span multiple lines. These types of comments are for explaining sections of code that may not be self-explanatory, especially before loops or if-else statements. However, we do not comment on code that is obvious. Here is an example of each:

// This is a single line comment. You start one with the //

/* This is a multi-line comment. There is a lot to be said in this comment 
*  that cannot be fit in one line, you start one with /* and end it with
*/

Javadoc Comments

Javadoc is the other type of comment that we will be looking at. Javadoc comments create documentation such as the class documentations we looked at back in Unit 2! These are very helpful, as from these, we can figure out what methods and classes do and how to use them. These are used only before methods and classes. Here is an example:

/** This a description of what the class, method, or constructor does, you start this
*   with /** (note that this has 2 asterisks instead of one)
*   and end like a multi-line comment.
*
*   Here, you also put **preconditions** as well, which are constraints
*   that your input must follow as well as **postconditions**, which
*   are constraints that the output must follow. These can also be put into 
*   regular comments as well. Preconditions have to be enforced by the user
*   and the programmer has no obligation to check for faulty output, however if
*   the programmer does, this is done with the use of try-catch and throw statements
*   which are beyond the scope of this unit's goals.
*/

Commenting our Two Classes

Using what we have learned, we will comment and document the two classes we have been working on!

/** Represents an assignment that a student will complete
*/
public class Assignment {
  private boolean correctAnswer; // represents the answer to an assignment, either T/F

  /** Makes a new assignment with one True/False question and sets the correct answer
  */
  public Assignment(boolean answer) {
    correctAnswer = answer;
  }
}

/** Represents a high school student
*/
public class Student {
  private int gradeLevel; // a grade between 9-12
  private String name; // the students name in the form "FirstName LastName"
  private int age; // the student's age, must be positive
  private Assignment assignment; // the current assignment the student is working on

  /** Makes a new student with grade gradeLev, name fullName, and age ageNum
  */
  public Student(int gradeLev, String fullName, int ageNum) {
    gradeLevel = gradeLev;
    name = fullName;
    age = ageNum;
    averageGrade = 0; // There is no grade since no assignments have been submitted
    assignment = null; // There is no active assignment at the moment
  }
}