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 "// comment.....shouldn't be used on consecutive multiple lines for text comments"

Copy pasted the relevant section here for convenience:

The // comment delimiter can comment out a complete line or only a partial line. It shouldn't be used on consecutive multiple lines for text comments; however, it can be used in consecutive multiple lines for commenting out sections of code.

Is there any rational reason for this?

Answer 1

Actually, I've been using // for multiple lines for years and never suffered any serious problem with it. I'm not a big fan of /*...*/ anymore because you get:

/* I'm commenting out all this code for a moment   ...   /* And here is a multi line comment      that was hidden in the middle */   ... */  

Thank the compiler it gets upset and tells me of the problem.

Where as:

... // And here is a multi line comment // that was hidden in the middle ... 

becomes with a single macro:

// ... // // And here is a multi line comment // // that was hidden in the middle // ... 

and is happily reversed with another single macro that returns it back to the original form

and as for:

  // but now you have    // trouble edditing   // your comments so   // that every  line   // is of equal size 

I say:

  // Tough, this is a piece of code not a    // published novel   // and if varying lengths   // make   // it hard for you to read then heaven   // forbid how you handle the code 

And don't you just hate edditing:

/******************************************************************  * Program: Foo.java                                              *  ******************************************************************  * Author:  Codey Art Work                                        *  * Purpose: To do something with something and get something not  *  *          forgetting something else.                            *  ******************************************************************  * Revision History:                                              *  ******************************************************************  *  Date  | Author |                                              *  *--------|--------|----------------------------------------------*  * 1/2/09 | Jack   | Now I have to keep all my comments in this   *   *        |        | tiny little space and if I edit it I just go *  *        |        | aaarrrrrrggggggggggghhhhhhhhhhh!!!!!!!!!!!!! *  ******************************************************************/ 

which always seem to appear in places insisting on /* */ over //

_{And I'd just like to say to the Stack Overflow guys, this is really cool editor. Doing code samples is so easy.}

Answer 2

The idea is that a multiline text comment is one entity - which you want to logically keep together. Line breaks in such a comment are nothing more than places to wrap text, so breaking it up into many "separate" comments makes no sense. Therefore, you construct a single comment block around the whole thing - using /* */.

For commenting out code, each line is its own logical unit, so using consecutive "//"s is ok - sometimes. This is especially true if individual lines could be commented back "in" for some reason, but not all of them. Though if you want to comment out a whole block code where it will never make sense to partially comment it in/out, you may still prefer to use /* */ - again to group everything together logically and visually.