Commenting

The commenting in an application can be divided into two type of commenting-

     1. External Comments – /** 

          a. These are extracted to HTML using a Java Doc tool. 

          b. These comments are supposed to tell the functionality of the code without getting into details of the code. Discussion of design issues is still valid though.

     2. Internal Comments- /*

          a. These are not extracted to Java Docs.

          b. These may contain the implementation comments. 

          c. Something we want the maintainer of the code to know.

However, as far as internal comments are concerned, these must be kept as low as possible. Whenever one feels the need to add a comment to his code, first attempt must be at making the code more readable.

Comment which must not be reformatted

/*-
 * This comment was not worthy of being mentioned in the java docs
 *           MUST NOT BE REFORMATTED
 */

/*- Tells the IDE not to format the given code


Single Line Comments

/* They must be preceded by a new line */


Trailing Comments

if (a == 2) {
    return true; /* special case */ 
} else { 
    return isPrime(a); /* works only for odd a */ 
} 

End-of-Line Comments

The // comment delimiter can comment out a complete line or only a partial line.


Documentation Comments

e.g.

/** 
 * Returns an Image object that can then be painted on the screen. 
 * The url argument must specify an absolute {@link URL}. The name 
 * argument is a specifier that is relative to the url argument. 
 * 
 * This method always returns immediately, whether or not the 
 * image exists. When this applet attempts to draw the image on 
 * the screen, the data will be loaded. The graphics primitives 
 * that draw the image will incrementally paint on the screen. 
 * 
 * @param url an absolute URL giving the base location of the image 
 * @param name the location of the image, relative to the url argument 
 * @return the image at the specified URL * @see Image 
 */ 
public Image getImage(URL url, String name) { 
    try { 
        return getImage(new URL(url, name)); 
    } catch (MalformedURLException e) { 
        return null; 
    } 
}

* Notice the inline tag {@link URL}, which converts to an HTML hyperlink pointing to the documentation for the URL class. This inline tag can be used anywhere that a comment can be written, such as in the text following block tags.

* If you have more than one paragraph in the doc comment, separate the paragraphs with a <p> paragraph tag, as shown.

* Use <code> style for keywords and names.

* Keywords and names are offset by <code>…</code> when mentioned in a description. This includes:

        – Java keywords

        – package names

        – class names

        – method names

        – interface names

        – field names

        – argument names

        – code examples

        – Use 3rd person (descriptive) not 2nd person (prescriptive).

For More on Commenting and Java Docs

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

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

Advertisements

About Gaurav

I'm Gaurav; friends call me Teddy, n i'm shivi fr my family!! A java enthusiast who likes experimenting with what he knows. View all posts by Gaurav

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: