Question

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

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

为方便起见，复制粘贴相关部分：

//注释分隔符可以发表评论完整的一行或仅一部分线。 不应该使用它连续多行文字评论;但是，它可以用于连续多行评论部分代码。

这有什么合理的理由吗？

Answer 1

实际上，我多年来一直在使用//多行，并且从未遇到任何严重问题。我不再是/*...*/的忠实粉丝了，因为你得到了：

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

感谢编译器它感到不安并告诉我这个问题。

其中：

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

使用单个宏：

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

并且很高兴与另一个将其返回原始形式的宏相反。

和至于：

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

我说：

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

你不喜欢喜欢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!!!!!!!!!!!!! *
 ******************************************************************/

似乎总是出现在坚持/* */而不是//

的地方

<子> 而且我想对Stack Overflow的人说，这是非常酷的编辑器。做代码示例非常简单。

Answer 2

这个想法是多行文本注释是一个实体 - 您希望在逻辑上保持在一起。这样的评论中的换行符只不过是用于包装文本的地方，因此将其分解为许多“单独”的注释是没有意义的。因此，围绕整个事物构建一个注释块 - 使用/ * * /。

对于注释掉代码，每一行都是它自己的逻辑单元，所以使用连续的“//”是有的 - 有时候。如果出于某种原因可以将“单个行”注释回“in”，尤其是所有行，则尤其如此。虽然如果你想要注释掉整个块代码，在其中部分注释进/出是没有意义的，你可能仍然希望再次使用/ * * / - 将所有内容逻辑地和视觉地组合在一起。

Answer 3

它使修改和格式化长注释非常痛苦。

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

Answer 4

即使用//评论大量代码，有时也会非常糟糕。

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

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

一些格式选项只会搞砸已注释掉的代码并将其全部转发出去，当你取消注释它时，所有地狱都会破坏厕所，你必须解析它并手动重新格式化。

我承认这是轶事，我已经重新配置了eclipse而不再这样做了，但我现在也不再使用//这么大的代码注释，而是支持/ * * /。但是，还有许多其他选项可以更好地使用：

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

如果您知道要创建不是java doc的多行注释，那么使用/ *启动它将在格式化的基础上处理其余部分。因此，为了解释在代码中修补的奇怪算法，我将使用/ * * /而不是//。我会在必要的时候保留单线。

我的2美分

Answer 5

我一直认为多行注释需要/ * * / style注释，因为//允许“连续多行注释掉代码段”。代码格式化工具需要能够轻松区分多行注释和注释掉的代码。

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

众所周知，许多样式规则至少有些随意，因此可能没有强烈的理由说明多线注释需要指定Java编程语言的代码约定/ * /样式注释。他们可能决定只使用/ * / style注释来评论代码，并使用//样式注释来表示单行和多行注释。

Answer 6

我会说我不会称之为“坏”。真的，这是一个常规问题，这是其他人所说的。除此之外，它可以使多行注释更令人沮丧（按键操作）。

老实说，我认为这是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
 */

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

Answer 7

可能是代码格式化的东西...如果你进行自动格式化（缩进），代码看起来会很难看。

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

Answer 8

根据我的经验，以下评论样式说明了我同意Java代码约定的原因。

Javadoc文档

/**
 * Description
 * @param foo refers to ...
 * @return true if...
 */

英文评论

/*
 * The sole reason for this unorthodox construct is just
 * to ...
 */
 synchronized(lockObject) {
     foo = bar;
 }

或

/* This is a single line comment */

注释掉代码（我不想签入注释掉的代码）。

// /* Accumulate the results */
// for (int i = 0; i < 10; i+=1) {
//     bar += result[i];
// }

为什么？

我喜欢在我的代码文件中使用最大宽度。 Eclipse在回复/ * * /块注释方面做得很好，所以要评论行宽设置。我喜欢英文书面文字的这种行为。评论会经常更新，否则你会得到：

  // This is a 
  // long broken up comment that has been edited multiple
  // times
  // and the developer was too lazy to fix the justification

或者你必须手动修复它的理由。

您不希望Eclipse重排已注释掉的代码，因此请使用//

其次，您可以突出显示一段代码，并在每行的开头添加和删除//样式注释。

注意，我总是用*开始一个块注释的每一行。以下只是惹麻烦：

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

为什么'//'样式多行注释不好（用Java）？

8 个答案: