Method Comments and Conditions¶
In industry you often produce code that other people will use and you will use code other people produced. It is important to document your code to facilitate understanding and reuse.
Method Comments¶
Recall that there are 3 types of comments in Java:
//Single line comment/*Multiline comment*//**Documentation comment*/
The special characters // are used to mark the rest of the line as a comment in many programming languages. If the comment is going to be multiple lines, we use /* to start the comment and */ to end the comment.
The multi-line comment, /** */ is called the documentation comment.
Java has a cool tool called javadoc that comes with the Java JDK that will pull out all of these
comments to make documentation of a class as a web page. This tool generates the official Java
documentation too, for example for the String class.
It’s a good idea to use the documentation comment in front of classes, methods, and
instance variables in case you want to use this tool.
The are some special tags that you can use in Java documentation. These are not required but many programmers use them. Here are some common tags:
@author Author of the program
@since Date released
@version Version of program
@param Parameter of a method
@return Return value for a method
The code below shows example commenting for a class and two enclosed methods.
/**
* The Converter program implements an application that
* converts inches to centimeters and prints
* the equivalent quantities.
*
* @author Fred Smith
* @version 1.0
* @since 2020-01-31
*/
public class Converter {
/**
* This method is used to convert inches to centimeters.
* @param inches A double representing a quantity of inches.
* @return double The equivalent quantity of centimeters.
*/
public static double inchesToCentimeters(double inches) {
return inches * 2.54;
}
/**
* The main method demonstrates use of the inchesToCentimeters method.
* @param args Unused.
* @return Nothing.
*/
public static void main(String[] args) {
System.out.println("10 inches = " + inchesToCentimeters(10) + " centimeters");
System.out.println("15.7 inches = " + inchesToCentimeters(15.7) + " centimeters");
}
}