Question

在阅读this维基百科关于doxygen的文章时，我发现了这句话：

许多程序员避免使用C风格的注释而是使用C ++ 风格单行评论。

这是对的吗？如果是这样，为什么呢？这只是一种习惯，还是有一些技术和理性的原因？

上述文章的例子：

/**
 * <A short one line description>
 *
 * <Longer description>
 * <May span multiple lines or paragraphs as needed>
 *
 * @param  Description of method's or function's input parameter
 * @param  ...
 * @return Description of the return value
 */

VS

/// <A short one line description>
///
/// <Longer description>
/// <May span multiple lines or paragraphs as needed>
///
/// @param  Description of method's or function's input parameter
/// @param  ...
/// @return Description of the return value

Answer 1

C风格的评论/* */ 不能递归嵌套。堆叠多个单行注释，就像这个'//////'，不是问题。这样，您可以逐步注释掉部分代码。例如，Visual Studio支持此功能，以此方式增加/减少注释级别的数量。

赞成'/ * * /' - 样式注释的一个原因是在滚动代码时使特殊类型的注释突出，例如方法文档。这也为代码创建了一个很好的视觉结构。

“/ * * /”评论的另一个用例是内联评论，其中包含代码双方，例如void myfunc(double size /* = 0 */) { ... }以使默认值在cpp文件。

结合两种好处的可能方法是：

在方法中使用'//'（您要反复注释/注销）和
仅对cpp中的doxygen文档等特殊类型的注释使用'/ * * /'。

Answer 2

现在既没有C样式注释也没有C ++样式注释，因为C和C ++都支持这两种注释，所以在一行的最后，最好使用//注释，而当使用/ * .. * / comments时，一长段注释更具可读性。

至于我，我通常更喜欢使用/ * .. * / comments来概括我在函数定义或声明之前放置的函数。如果我需要在一些代码片段中的某些语句中添加注释，只需插入一行注释即可使用// coments。

Answer 3

我认为这真的是一种品味问题。

有许多约定，只要有多个选项可用，总会有讨论。匈牙利与非匈牙利符号，蛇案与骆驼案等相同。

一般来说，这取决于几个因素：

1）什么是可接受的风格。如果你在大型项目中工作，你通常必须（并且应该）遵守编码风格的一般规则。在同一项目的各种文件中使用不同的注释样式是非常不受欢迎的。

2）大多数球队喜欢的。应讨论接受的惯例以适应开发人员的偏好。应该没有压力 - 只要每个人都认为一切都很好。

3）技术要求是什么。如果你需要某种形式的嵌套，你应该仔细考虑。多行注释不能嵌套。按以下顺序：

/* -> 1 start
/* -> 2 start
*/ -> 2 end
*/ -> 1 end

'2 start'不会被识别为注释，'2 end'将匹配'1 start'而'1 end'将引发编译错误。

4）当应该使用特定评论时。在创建类的一般描述时（例如），人们可能希望使用/ * * /创建多行，强描述性注释。在代码的一部分（单个表达式，方法参数描述或附加注释）中插入简短描述时，简单的单行注释（//）可能是更好的主意。

另外，值得一提的是，ML注释被假定为多行。它的意思是：在Visual Studio中，例如，在创建DOC注释后：

/**
 *
 */

在评论中按Enter键后，将自动添加

star（*），这样您就可以创建漂亮的评论而无需额外的工作：

/**
 * Some nice description [pressing enter here]
 * //-> this was inserted by editor
 */

如果使用单行标记（//）进行多行注释，则需要手动在每行添加它们。

有一种情况，您应该使用单行注释：使用Visual Studio。那是什么意思？ VS有一个很好的功能来评论/取消注释代码块。这些任务有一些特殊的快捷方式 - Ctrl-K，Ctrl-C用于评论和Ctrl-K，Ctrl-U用于取消注释。现在，编辑将检查应该使用哪种评论：

void f()
{
  int p = 0;
  int k = 0;
  while(true) {
    ++p;
    ++k;
  }
}

让我们评论整个功能[按Ctrl-K-C ...]。这是结果：

//void f()
//{
//  int p = 0;
//  int k = 0;
//  while(true) {
//    ++p;
//    ++k;
//  }
//}

让我们在身体上发表评论并将其设为空[按Ctrl-K-C ...]。这是结果：

void f()
{
  int p = 0;
  int k = 0;
  while(true); /*{ -> comment was invoked inside the line, multiline is required.
    ++p;
    ++k;
  }*/
}

在预测时，使用单行注释非常重要，可能会暂时从源代码中排除某些代码部分。让我们想想如果我们的身体包含一个评论会发生什么：

1）第一种情况，SL评论：

//void f()
//{
//  int p = 0;
//  int k = 0;
//  while(true) {
//    ++p; //some comment -> ok, '//' can be nested
//    ++k;
//  }
//}

2）第一个案例，ML评论：

//void f()
//{
//  int p = 0;
//  int k = 0;
//  while(true) {
//    ++p; /*some comment*/ -> ok, '/**/' can be nested inside //
//    ++k;
//  }
//}

3）第二种情况，SL评论：

void f()
{
  int p = 0;
  int k = 0;
  while(true); /*{ -> comment was invoked inside the line, multiline  is required.
    ++p; //some comment -> ok, '//' can be nested inside multiline 
    ++k;
  }*/
}

4）第二个案例，ML评论：

void f()
{
  int p = 0;
  int k = 0;
  while(true); /*{ -> comment was invoked inside the line, multiline  is required.
    ++p; /*some comment*/
    ++k;
  }*/ -> oh..
}

由于SO使用相同的规则解析注释，您应该看到上一个示例中的最后一个标记不是灰色的。从我的角度来看，这是一件很重要的事情，因为我经常使用块（un）评论。

Answer 4

这完全是一个什么是可接受的风格的问题 - 没有任何技术原因可以使用一种风格而不是另一种风格（除非你有一个非常古老的编译器）。

有些社区会期望一种风格的评论 - 例如Linux内核（一个C社区）会期待C风格的评论，但内核源代码的快速插图显示了一些C ++风格的评论已经成功。

因此，如果您正在为项目做出贡献，那么您应该遵循已经在那里使用的样式。如果你是单独或类似的工作，你可以使用你喜欢的 - 虽然最好不要混合风格。

在C ++代码中使用C风格的注释是不好的做法？

4 个答案: