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

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 2

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];
}
*/

Answer 3

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 4

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.

Answer 5

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 6

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.