Why is '//' style multiline comment bad (in Java)?

Question

http://java.sun.com/docs/codeconv/html/CodeConventions.doc4.html#286

I was reading the above section of Java coding convention and started to wonder why it says \"// com

Answer 1

In my experience the following commenting styles illustrates why I agree with the Java Code Conventions.

Javadoc documentation

/**
 * Description
 * @param foo refers to ...
 * @return true if...
 */

English comments

/*
 * The sole reason for this unorthodox construct is just
 * to ...
 */
 synchronized(lockObject) {
     foo = bar;
 }

or

/* This is a single line comment */

Commenting out code (I prefer not to check in commented out code).

// /* Accumulate the results */
// for (int i = 0; i < 10; i+=1) {
//     bar += result[i];
// }

Why?

I like to use a max width in my code files. Eclipse does a nice job of reflowing /* */ block comments so to justify with you comment line width settings. I like this behavior for English written text. Comments get updated often and you would otherwise have:

  // This is a 
  // long broken up comment that has been edited multiple
  // times
  // and the developer was too lazy to fix the justification

or you have to fix it justification manually.

You don't want Eclipse to reflow commented out code so use //

Secondly, you can highlight a block of code and add and remove // style comments to the start of each line.

Note, I Always start every line of a block comment with a *. The following is just asking for trouble:

/* Accumulate the results */
/*
for (int i = 0; i < 10; i+=1) {
    /* comment broke the outer comment : Sigh! */ 
    bar += result[i];
}
*/