COMP 310

Commenting in Java

    Current Home  Java Resources  Eclipse Resources

Comments are an integral part of any program. They help the person reading the code (often you) better understand the intent and functionality of the program. It is critical that you get in the habit of always commenting your code and doing it as you write your code, not after the fact.

The tools we will use in this class will remind you to write comments, help you to write those comments, and will exploit the comments you have written to make your programming life easier. Use them.

Type of Comments

There are two types of comments that should appear in programs: documentation comments and implementation comments. Documentation comments describe the semantics of a class, field, or method. Good documentation comments should allow you to use the class and its methods without having to read any source code. In contrast, implementation comments are used to clarify how a particular piece of code operates. While you should write implementation comments when you feel they are necessary, documentation comments are an integral part of programming and are mandatory in this class.

Style

By convention, in Java, documentation comments are set inside the comment delimiters /** ... */ with one comment per class, interface, or member. The comment should appear right before the declaration of the class, interface or member and each line of the comment should begin with a "*".

Here is a ridiculous class that serves as an example of how to format your comments (not as an example of how to write Java code):

/**
 * The Foo class is a silly example to illustrate documentation 
 * comments.
 */
public class Foo { 
    /**
    * An integer to keep track of for fun.
    */
    private int count; 
    ... 
    /**
    * Increment a value by delta and return the new value. 
    *
    * @param  delta   the amount the value should be incremented by
    * @return         the post-incremented value
    */
   int increment(int delta) {
       ...
   }
} 

Notice that the comments are formatted similarly in all cases and the leading "/" is indented at the same level as the code being commented.

Notice also that the method comment includes the "@param" and "@return" tags. This indicates the name of all of the parameters and what is returned by the method. Eclipse will generate these automatically for you if you simply type "/**↵" after having written the method declaration.

Obviously, including such comments is good practice, as you will be able to look back at your code and understand it better. Similarly, others will be able to understand your code better. However, formatting them in this way has additional benefits. Tools can be used to parse these comments and generate documenation for your code (hence the name documentation comments). The javadoc tools can read these comments and generate HTML-style documentation. Eclipse can also read these comments. When you type an object name and then the "." operator, it will list all of the methods supported by that object's class. When you hover over a method call, you will get nicely formatted documentation, as well.

UML Lab will ask you for comments whenever you add a new element.  If you get in the habit of typing them right then, you will not need to do much additional work to keep your code properly commented.

Generating Javadoc Web Pages

The beauty of Javadocs is that the Java system knows how to read the comments on all Java elements and convert them into standardized, nicely formatted, easy-to-read web pages. 

In Eclipse, one simply does the following:

  1. In the Package Explorer, right-click the desired project.
  2. Select Export.../Javadoc and click Next.
  3. The first time you generate Javadocs, the "Javadoc command" may not be set. 
  4. By default, the entire source code will be selected.
  5. Select "Private" for the visibility level to be generated.   This will generate all possible Javadocs.
  6. Select the "standard doclet"
  7. Click Next.
  8. Enter a meaningful Document title and click Finish

 

Expectations

Throughout COMP 310, you will always be expected to write documentation comments for all code that you write and it will be a part of your grade for each project!

You must write documentation comments for all:

You will see the benefits of doing so immediately, as Eclipse will use your comments to make your life easier.

You can learn more about javadoc and documentation comments here:

http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

It is highly recommended that you comment all auto-generated fields and methods such as those created by your GUI-creating tool, e.g. WindowBuilder.   Doing so will enable Eclipse to show you what every variable is used for plus will greatly enhance your or someone else's ability to understand the code later.   Comp310 will not require this however due to the tedium involved.  In general however, the benefits will outweigh the effort of the extra work.     Commenting everything is the right thing to do. 

IMPORTANT:

 

Javadoc Tips

Autogenerate @param and @return:

In Eclipse, simply typing "/**<Enter>" before a method or class will automatically generate in all necessary @param and @return attributes.

Set compiler to warn about missing Javadocs

In Eclipse, under Preferences/Java/Compiler/Javadoc,  set the compiler to warn or throw errors on missing or malformed Javadocs.   This can be very useful in making sure that all code is properly documented!

Suppressing "self-closing element not allowed" warnings

The Javadoc compiler ion the Java 8 JDK adheres to HTML 4.01 standards, where "void element" tags (tags with no enclosing content) such as br and image are written without the closing "/", as is allowable in the more regularized HTML 5 standard:

Because of this adherence to the old HTML standard, by default, Javadoc will throw a "self-closing element not allowed" warning whenever an HTML 5 formatted void element tag is encountered.

To stop Javadoc from throwing this warning, invoke Javadoc with the following command line parameter:

-Xdoclint:all,-html

This will suppress the HTML "lint" style checker.   It is unclear, unfortunately, from the Javadoc documentation what other style checks are also suppressed with this option.

In Eclipse, this option can be set when one performs an Export/Javadoc operation by typing in the above option (including the starting "-" symbol) in to the "Extra Javadoc options" box in the "Configure Javadoc arguments" dialog panel when it appears.

 

Sharing Your Javadocs with Others

Generated Javadocs are just regular HTML web pages.   The problem is that if you want to share them with other people, you need a web server.

Luckily, Rice gives everyone a simple way to show web pages using your "U: drive":

All you need to do is to copy your Javadocs into a folder under U:/Public/www and it will be accessible through any browser.  See the documents linked above for information on who to determine the exact URL of your Javadocs.    

 


© 2017 by Stephen Wong