Java comments how-to

Today's tutorial will explain comments in Java and how to create them. Every developer worth their salt uses comments. Not only in Java, but in every programming language. Comments can be used to explain what a particular part of the code is doing. This is useful to yourself and anyone else working on your code later down the road. If you are making an API, you probably want to make javadoc comments so that people using your API know how to use it.


Single line comments

Single line comments are created using a double forward slash. The compiler ignores everything from // to the end of the line.

Multi line comments

Multi line comments are used when you want to write longer sentences to explain your code in more detail. A multi line comment starts with /* and ends with */

Javadoc comments

Javadoc comments are used so that you can list out any classes, methods, variables neatly in an html document. This is especially important when you are creating an API to share with others. They need to know which classes to use, how to call your methods, etc. Javadoc comments start with /** and end with **/. You can also add tags, such as @author for your class and @param to list out the parameters of a method.

How to generate javadoc using Eclipse

After you have completed your programming and have all your javadoc comments in, you will need to generate the html doc. To do this I will use eclipse:

Step 1:

Choose 'Project' from your toolbar, then click 'Generate javadoc'



Step 2:

Set the location of your javadoc.exe (this will be in your jdk/bin folder). Then make sure you have the packages and classes you want to see in the javadoc checked. Click 'Next >'



Step 3:

Last step. Give your document a title and press 'Finish'



Step 4:

You will now see that Eclipse has generated several files within your project. A folder named 'doc' is listed and has several things inside. To view the html output you created, go to your workspace folder and find your project/doc folder and then drill down inside your package (com.houselantaff.tutorials for me) and view your 'package-summary.html'



Example from the HelloWorldApp


package com.houselantaff.tutorials;

/**
 * This is a javadoc comment;
 * It is currently used to describe the HelloWorldApp class
 * 
 * @author HouseLantaff
 *
 */
public class HelloWorldApp {

	public static void main(String[] args) {

		/*
		 * This is a multi line comment
		 * Developers commonly use these when they need to write more then one or two lines of comments.
		 */


		//Single line comment: The below line calls the sayHello method and passes 'HouseLantaff' as a String.
		sayHello("HouseLantaff"); 

	}

	/**
	 * This is a javadoc comment used to describe the below method.
	 * @param name - This is a String being passed to our method.
	 */
	public static void sayHello(String name) {
		System.out.println("Hello, "+name);//Single line comment: This line prints the message to the console.
	}

}

				

To see the javadoc generated using this example, click here