COMP 310	Commenting in Java

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. 
   • If unset, click the configure button and browse to the Java JDK installation folder and select the javadoc.exe file.
4. By default, the entire source code will be selected.
   • If desired, unselect any packages for which you do not wish documentation to be generated.
5. Select "Private" for the visibility level to be generated.   This will generate all possible Javadocs.
6. Select the "standard doclet"
   • Browser for the destination folder for your documentation.   Typically, this is a "doc" folder just below the root of your project.  
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:

• Classes and interfaces
• Fields
• Methods, including all input parameters and return values

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: Documentation Comment Specification for the Standard Doclet (JDK 17) (oracle.com)

You should also comment all auto-generated fields and methods such as those created by your GUI-creating tool, e.g. WindowBuilder or other code generator, such as UML Lab.   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.   While this may appear tedious at first, the benefits will outweigh the effort of the extra work.     Commenting everything always is the right thing to do. 

It is highly recommended that you add internal "//" type comments to document what your code is trying to do. This will save hours of unnecessary debugging work when you forget what a method is trying to do!

IMPORTANT:

• Don't forget to comment any auto-generated method where you have written code in the method body, such as the actionPerformed method of a button click listener, in order to describe the behavior of your code!

Docs for Overridden Methods

While it is tempting to omit documenting overriding methods (i.e. marked with the annotation "@Override"), this is really only justifiable if the documentation for the implementing entity would not add anything to the documentation provided by the abstract definition of the method. However this situation is quite rate because all implementations of an abstract method differ in some manner. It is important to capture those differences so that the users of those methods understand the differences between one implementation and another.

Unfortunately, when adding Javadocs to an overridden method, those Javadocs completely replace the documentation of the abstract method being overridden. Since that abstract description still applies, it is helpful to include it in the augmented documentation of the implementing method. This can be easily accomplished by using the "{@inheritDoc}" tag:

	/**
	 * {@inheritDoc}
	 * This inserts the docs from the overridden method above.
	 * Implementation-specific docuementation can then be added here.
	 */
	 @Override
	 public void someMethod() {
	 
	 }
	

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:

• HTML 4.01:  <br>, <image ...>
• HTML 5:  <br/>, <image .../>

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":

• Hosting a personal web site:  https://kb.rice.edu/page.php?id=70749
• Mounting your U: drive: https://kb.rice.edu/search.php?q=mount+drive&cat=0

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