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. Examples of all three styles follow:

Is there any rational reason for this?

Answer 1

It creates code that's harder to maintain, when dealing with large blocks. Your editor might support a function that comments in and out large blocks of code using //, but that doesn't mean that my editor does. That means that its quite possible that i'll end up having to manually remove the comment block from each line because of my (admittedly) inferior editor. Another good reason is that it confuses some version control systems.

Basicly it's just logic - use multiline comments (c-style) for multiline blocks and single-line comments (c++-style) for single lines.

Answer 2

It makes modifying and formatting long comments extremely painful.

Most editors provide some sort of wrapping facility to automatically wrap text into lines of readable length. If every line starts with a '//' those will get moved around, then have to be deleted, and new ones re-inserted. All that tedious work can be avoided using '/* */ style comments.

Answer 3

Even commenting large quantity of code with // can be quite horrible sometimes.

I use Eclipes and although I really enjoy the drudgery it takes out of everyday programming there are some feature combination that can give weird results... for example..

select large block of code that already contains some // multiline commented out code, press ctrl-/ and comment it all out, then do ctrl-shift-f to format your code, if for some reason your formatter deals with comments it will reformat your code. Then reselect the whole thing and uncomment it with ctrl-/ again...

some format options will just screw around the commented out code and relay-it all out, when you uncomment it all hell breaks loos and you will have to parse it and reformat it manually.

I admit this is anecdotal, I have since reconfigured eclipse to not do this anymore but I also refrain now from using // for such large code comment swath in favor of the /* */. However there are many other options that are better to use :

/** for Javadoc comment */ this way the comments are accessible in code complete, documentation etc... comment once, use everywhere.

If you know you are going to create multi line comment that is not java doc then starting it with /* the IDE will take care of the rest as far as formatting goes. So to explain weird algorithms of patching in the code I will use /* */ rather than //. I keep it for single liner when necessary.

My 2 cent

Answer 4

I've always thought that /* */ style comments were required for multi-line comments because // was allowed "in consecutive multiple lines for commenting out sections of code." Code formatting tools need to be able to easily distinguish multi-line comments from commented out code.

If you tell a code formatting tool (or your IDE) to cleanup your file, you would likely want it to re-wrap multi-line comments to the margin, wrapping at the spaces. You would not what the tool to wrap commented out code this way.

That all said, many style rules are at least slightly arbitrary, so there may not have been a strong reason why Code Conventions for the Java Programming Language specified /* / style comments were required for multi-line comments. They could have instead decided to use / */ style comments only for commenting out code, and use // style comments for single and multi-line comments.

Answer 5

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.

Answer 6

I will say that I wouldn't call it "bad". Really, its a matter of convention, which is what others have said. There is nothing inherently bad about it, except that it can make multi-line comments a bit more frustrating (keystrokes-wise) to work with.

Honestly, I think it is a double standard with javadoc. Javadoc requires:

/**
 * Validates a chess move. Use {@link #doMove(int, int, int, int)} to move a piece.
 * 
 * @param theFromFile file from which a piece is being moved
 * @param theFromRank rank from which a piece is being moved
 * @param theToFile   file to which a piece is being moved
 * @param theToRank   rank to which a piece is being moved
 * @return            true if the chess move is valid, otherwise false
 */

and I don't understand why the repeated " * " is any better than "//". So, to me, there's nothing inherent about // being bad (because editors can be set up to automatically add them to multi-line comments) and just convention and common practice.

Answer 7

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 your 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 8

may be for code formatting stuff ... if you did auto formatting (indentation) the codes will looks ugly.

in some text editors, comments using /** ... **/ could be folded so it will make easier to read the code.