Why is '//' style multiline comment bad (i

问题:

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?

回答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.}

回答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.

回答3:

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.

回答4:

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

回答5:

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.

回答6:

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.

回答7:

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.

回答8:

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