CODEWITHSUNDEEP
javaeclipsecommentsjavadoc
Fabian Zeindl
Fabian Zeindl

Reputation: 5988

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

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 /** */ ?

Upvotes: 3

Views: 16414

Answers (8)

peq
peq

Reputation: 329

If you use the reference formatting (e.g. {@link ClassA}) and rename the class ClassA with Eclipse, it will automatically update the comment if it is a javadoc comment.

Upvotes: 0

Paschalis
Paschalis

Reputation: 12291

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.

Upvotes: 9

fge
fge

Reputation: 121692

/** .... */ 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.

Upvotes: 4

AlexR
AlexR

Reputation: 115328

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.

Upvotes: 10

arcy
arcy

Reputation: 13103

Javadoc treats /** differently; classes and methods which have /** comments above them will get put into javadoc output.

Upvotes: 2

Nanne
Nanne

Reputation: 64399

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.

Upvotes: 4

Oliver Charlesworth
Oliver Charlesworth

Reputation: 272447

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.

Upvotes: 3

mike3996
mike3996

Reputation: 17497

Yep, it's the javadoc notation to use /** Primary sentence. Other descriptions... */. First sentece up to the . will be used in summaries of javadoc and the rest in the detailed view.

Upvotes: 2

Related Questions