为什么“//”样式的多行注释不好（在 Java 中）？

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

提问by Indhu Bharathi

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

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"

我正在阅读 Java 编码约定的上述部分，并开始想知道为什么它说“// 注释.....不应该在连续的多行文本注释上使用”

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?

这有什么合理的理由吗？

回答by Swanny

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 | Hyman   | 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.}

_{我只想对 Stack Overflow 的人说，这是一个非常酷的编辑器。做代码示例是如此简单。}

回答by levik

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.

对于注释掉代码，每一行都是它自己的逻辑单元，所以使用连续的“//”是可以的 - 有时。如果出于某种原因可以将个别行注释回“in”，但不是全部注释，则尤其如此。尽管如果您想注释掉整个块代码，而在其中部分注释掉/注释掉它永远没有意义，您可能仍然更喜欢使用 /* */ - 再次将所有内容在逻辑和视觉上组合在一起。

回答by Charles E. Grant

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.

大多数编辑器提供某种包装工具来自动将文本包装成可读长度的行。如果每一行都以 '//' 开头，这些将被移动，然后必须删除，并重新插入新的。使用 '/* */ 样式注释可以避免所有繁琐的工作。

回答by Newtopian

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

我使用 Eclipes，虽然我真的很喜欢它从日常编程中消除的苦差事，但还是有一些功能组合可以产生奇怪的结果......例如..

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

选择已经包含一些 // 多行注释掉的代码的大块代码，按 ctrl-/ 并将其全部注释掉，然后执行 ctrl-shift-f 来格式化您的代码，如果由于某种原因您的格式化程序处理注释，它将重新格式化你的代码。然后重新选择整个内容并再次使用 ctrl-/ 取消注释...

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 :

我承认这是轶事，此后我重新配置了 eclipse 以不再执行此操作，但我现在也避免使用 // 用于如此大的代码注释带，而是使用 /* */。但是，还有许多其他更好的选择：

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

/** 用于 Javadoc 注释 */ 这样可以在代码完整、文档等中访问注释...注释一次，随处使用。

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.

如果您知道要创建不是 java doc 的多行注释，则以 /* 开头，IDE 将处理其余的格式化工作。因此，为了解释代码中奇怪的修补算法，我将使用 /* */ 而不是 //。必要时我将它保留为单衬。

My 2 cent

我的 2 美分

回答by NamshubWriter

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.

如果您告诉代码格式化工具（或您的 IDE）清理您的文件，您可能希望它重新包装多行注释到边距，在空格处换行。你不会用什么工具来包装注释掉的代码这种方式。

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.

尽管如此，许多样式规则至少有点随意，因此可能没有充分的理由说明为什么 Java 编程语言的代码约定指定 /* / 多行注释需要样式注释。他们本可以决定使用/*/ 样式注释仅用于注释代码，而使用// 样式注释用于单行和多行注释。

回答by poundifdef

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. Javadocrequires:

老实说，我认为这是对 javadoc 的双重标准。Javadoc要求：

/**
 * 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.

我不明白为什么重复的“*”比“//”好。所以，对我来说， // 不好（因为编辑器可以设置为自动将它们添加到多行注释中）并没有什么内在的，而只是约定和惯例。

回答by nightingale2k1

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.

在一些文本编辑器中，注释 using/** ... **/可以折叠，以便更容易阅读代码。

回答by Doug Coburn

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

根据我的经验，以下注释样式说明了为什么我同意 Java 代码约定。

Javadoc documentation

Javadoc 文档

/**
 * 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:

我喜欢在我的代码文件中使用最大宽度。Eclipse 在重排 /* */ 块注释方面做得很好，因此可以证明您的注释行宽设置是合理的。我喜欢英语书面文本的这种行为。评论会经常更新，否则您将拥有：

  // 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 //

您不希望 Eclipse 回流注释掉的代码，因此请使用 //

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

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