Is it a bad practice to use C-style comments in C++ code? [closed]

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 8 years ago.

Improve this question

While reading this wikipedia article about doxygen, I came across this statement:

Many programmers avoid using C-style comments and instead use C++ style single line comments.

Is this correct? If so, why is that? Is it just a habit or there are some technical and rational reasons behind this?

---

Examples from aforementioned article:

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

The C-style comments /* */ cannot be nested recursively. Stacking multiple single line comments on each other, like this '//////', is not a problem. This way you can comment out a part of the code incrementally. Visual Studio for example supports this with functionality to increase/decrease the number of comment levels in this fashion.

A reason in favour of '/* */'-style comments is to make special types of comments stand out when scrolling through the code, such as method documentation. This creates a nice visual structure to the code as well.

Another use-case of '/* */' comments are the sort of inline comments which have code to both sides, such as void myfunc(double size /* = 0 */) { ... } to make a default value visible in the cpp file.

A possible approach to combine both benefits is:

• use '//' inside methods (where you want to comment in/out out repeatedly) and
• use '/* */' only for special types of comments like doxygen documentation in the cpp for example.

Answer 2

Now there is no neither C style comments nor C++ style comments because both C and C++ supports the both kinds of comments, So in the end of a line it is better to use // comments while a long block of comments is more readable when /* ..*/ comments are used.

As for me I usually prefer to use /*.. */ comments for general description of functions which I place before function definitions or declarations. If I need to add a comment to some statement inside some snippet of code and it is enough to insert only one line of comments I use // coments.

Answer 3

It is really a matter of taste, I think.

There are many conventions and wherever more than one option is available, there will always be a discussion. Same goes for hungarian vs non-hungarian notation, snake-case vs camel-case etc.

Generally, it depends on few factors:

1) What is the acceptable style. If you work in large project, you usually must (and should) obey to general rules of coding style. It is very undesired to have different commenting styles in various files of the same project.

2) What most of team prefers. Accepted convention should be discussed to fit preferences of developers. There should be no pressure - as long as everybody agrees everything is fine.

3) What are the technical requirements. If you need some form of nesting, you should think carefully. Multiline comment cannot be nested. In following sequence:

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

'2 start' wont be recognized as a comment, '2 end' will become match for '1 start' and '1 end' will raise compiler error.

4) When particular comment is supposed to be used. When creating general description of classes (for example), one probably wants to create multi-line, strongly-descriptive comment using /* */. When inserting short descriptions inside a part of code (single expressions, method arguments descriptions or additional notes), simple, single-line comment (//) would be probably a better idea.

Also, it is worth to mention, that ML comments are assumed to be multi-line. What does it mean: in Visual Studio, for example, after creating DOC comment:

/**
 *
 */

star (*) will be added automatically after you press enter inside the comment, allowing you to create good-looking comment with no additional work:

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

In case of multiline comments using single-line marker (//), you would need to add them at each line manually.

There is one case, when you should use single-line comment: working with Visual Studio. What do I mean by that? VS has a nice feature to comment/uncomment a block of code. There are special shortcuts for these tasks - Ctrl-K,Ctrl-C for commenting and Ctrl-K,Ctrl-U for uncommenting. Now, the editor will check what kind of comments should be used:

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

Let's comment whole function [Pressing Ctrl-K-C...]. This is the result:

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

Let's comment while body and make it empty [Pressing Ctrl-K-C...]. This is the result:

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

It is very important to use single line comment when you predict, that some parts of code may be temporarily excluded from source. Let's think what would happen if our while's body contained a comment:

1) First case, SL comment:

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

2) First case, ML comment:

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

3) Second case, SL comment:

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) Second case, ML comment:

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

Since SO parses comments with the same rules, you should see that last marker in last example is not greyed out. From my point of view this is an important thing, as I very often use block (un)commenting.

Answer 4

This is entirely a question of what is acceptable style - there are no technical reasons to use one style and not the other (unless you have a very old compiler) in either language.

Some communities will expect comments in one style - eg the Linux kernel (a C community) will expect C style comments, but a quick grep of the kernel sources shows some C++ style comments have made it in.

So, if you are contributing to a project then you should conform with the style that is already used there. If you are working alone or similar you may use what you prefer - though it's best not to mix styles up.