Inline comments in Java: /** opposed to /*?

Question

is there a reason i should prefer to write inline-comments in java like this:

/** Init operation */
mindControlLaser.engage();

as opposed to use just one *:

/* i'm a happy comment */

Eclipse colours the syntax differently, but is there really anything in the "toolchain" (javadoc, eclipse, etc.) giving me an advantage when using /** */ ?

Solution 1

No reason for inline comments.

/** signals to javadoc utility to extract documentation about your API automatically. It does not have any effect when is used inside methods.

Solution 2

Regular comments

/* Regular comment */

With regular comments you explain maybe a part of an algorithm that is tricky. Or anything that you don't want to be a part of the JavaDOC. Inline comments are regular comments too, and can be used for example when the description is shorter.

Java Documentation

/** JAVA DOC COMMENT */

With javadoc you explain classes, methods, or fields(variables).

Then, most IDEs like Eclipse can use this information to help you while you code. For example, if you have a classA and a classB, and in classB you use stuff from classA, then if you hover on methods or variables you can see the JavaDOC information. It's very handy.

Also, with build tools like ant you can automatically build HTML files out of the JavaDOC, and if you publish them you can allow others to reuse your work. Look for example the documentation of Java itself here.

Solution 3

The syntax for a comment is /* */.

Javadoc has as a default that you use /** */. This is a comment because the second * is inside the comment, so would not be seen differently by your compiler.

So without a second * you are just adding a comment, and with the second one you write javadoc: eclipse will recognize it and give you hints etc when hovering on the functioncall somewhere else.

Solution 4

/** .... */ will generate Javadoc, /* ... */ won't.

Of course, it will generate Javadoc only when in the correct places. Javadoc also has a pretty well defined format, see here.

Solution 5

The /** denotes "documentation" comments; Javadocs etc. look for these when creating documentation for your code.

So they should really only be used above methods and classes, e.g.:

/**
 * Class to represent tigers.
 */
class Tiger {
    /**
     * Go extinct.
     */
    void goExtinct() {
    }
}

The /* variant just denotes a standard comment block.

View more solutions