[C] Why do people write comments using /* ... */ ?
 

There's something I don't understand and has been bugging me for a while. After browsing the GPL'ed C source code for a lot of programs I noticed that people will often write code comments by using the "/* ... */" notation rather than "//". For example consider the following three comments:
Why the hell are #1 and #2 so often used in place of #3? I understand that #1 allows you to place comments on multiple lines, and I even welcome it in the file header. But people will often put them inside the code too, which I personally find extremely irritating. Why? Because they interfere whenever I try to comment out large chunks of code by using /* --- */. Arse! Also, why even use #2 instead of #3?

Thoughts?

Use #ifdef 0 to comment out blocks of code.

The // style comment was introduced to C in the C99 standard. Before that, /* ... */ (and #ifdef 0 as dugan pointed out) was the only valid way to comment C code.

I also find it annoying. I always use // comments, except when excluding code.

Ah I see. The "/* ... */" notation predates the "//". Now it makes sense.

Do it any way that you prefer, but, within a single module or application, do it consistently. Follow the practices of the folks who worked on the code earlier.

i'll confess to a bad habit. i block comment like thisit results in a warning but its easier to copy-pasta/dd in vi.

I prefer block-comments to line-comments because word-wrapping (as done for example by mail clients) will not break the code. There is no compelling argument for why line-comments are better.

^ line-comments are easier to type.

No braces around single-statement if bodies are easier to type as well, but omitting them is a bad idea. For me “easier to type” is not a compelling argument in this instance (and if you're using reasonable editor you probably can configure it to enter comments with some simple keystroke).

I find it more useful to use // for comments and /**/ for excluding code. I don't care how easy or difficult it is to type, I care about functionality. It is true that #ifdef can also be used in case someone used exclusively /**/ for comments.

As many have said, the rules are flexible, also because of the evolution of how comments can be added to code.

I have to admit to being consistently, inconsistent:for multi-line block comments, file/function/section headers.for one-line comments, also many times comments at the end of a code line. My only rule is that I will not put a comment within an if or loop top line statement:To me those are potential, if not really; syntax errors.

I will use "//" to comment out one or two lines, for instance if I have a "potential fix" or even one that's definitely a fix; I may copy the line to change, then use // to comment out the original and make my change in the new copy so that I can leave the original code for a while. Similarly I may use "//" when appending a comment to the end of a line, merely being lazy as a typist.

To comment out code blocks, I do use #if 0

I see absolutely nothing wrong with using /* */
both styles are perfectly valid so there should be no reason for it to irritate you.

That said, I HATE #if 0
It is very non-intuitive and many syntax-highlighters will not detect it so it is east to miss that it is "commented" out

So then, how do you comment out code ?

For a block with no */ I use /* */
Otherwise I guess you would have to resort to something like that. But I avoid it because it is hard to read

If it's not needed, just delete it…

Well yes, but what about when you are debugging ? Say you want to test two or more pieces of code ? Yes, you can do it with the preprocessor, but smeezekitty said he hates it. So, if he hates the preprocessor but doesn't mind /**/ comments everywhere, then what is his solution ? I thought maybe he had one. Of course, it could be just a rant.

The problem with abusing the preprocessor like that is the code path become unclear.
Usually I just use /* */ to comment it out. That is one disadvantage of using those
comments in code is that you lose that ability. I still don't mind them though

When I am testing sometimes I mark the code position and cut the code and paste it to another file.

Or one can delete the code, build debug version, and then undo changes on the file (any serious editor has that functionality). Or rename a function to something else while they test its different implementation. Or add code at its beginning and add “return” at the end of the new code so that the old one is unreachable. Or even wrap the code in “if (0) { … }”.

There are so many options that I don't recall when was the last time I used “#if 0”.

That is also a possibility.

I don't really get what are we talking about, but I think that's what "if" is good for.

Yeah, I don't know why anyone would write comment markers by hand. In Emacs, I can just use comment-dwim (M-;) which comments or uncomments the marked region. For example, with all the code marked, comment-dwim toggles between these 2:

As you can see, it handles existing /* */ comments by escaping the comment markers.

Certainly most IDEs can handle things properly. However, you can't just assume that everyone has a good IDE. I mean why else are Linux kernel devs so strict about style ? With a good IDE you can set your own style, but ... they're still strict about it.

For one, code is not always read in an IDE. For example, a lot of kernel code I read, I read in my mail client (or LKML archives).

If someone writing code does not have a decent editor, then their first priority is to get one, and not worry about comment style.

I end up using #if 0 #else #endif a lot because there are some prototype projects where they change the lower sensory layers a lot because they want to test which are better, but we want to keep the capability to talk to the other ones until we reach a final conclusion. As a result it's better to take the entire function and #if 0 it out until we know which direction we're going in.

The other thing there is if you try to /* */ the whole function, any random comment in the middle of that screws your attempt up.

And #if 0 is not perfect either, you have to have legal code within it. Make a file with bad syntax or just non-code within #if 0 and it won't always compile if you happen to have syntax based terms in there, for instance ";".

All a matter of preference though. I'm glad that C is C and I rarely encounter anyone's code that is unreadable; bad maybe, but not unreadable.

In that case, define a macro and do “#if THAT_MACRO” and not “#if 0”, e.g.:

LOL Mina86, not in the project I'm on; the hardware changes come rapidly for "experiementation" purposes and then suddenly I have to support both in one software release (therefore no preprocessor directive but instead true if-else). The coupe de grace is "can we get BOTH of those at the same time so we can parallel their data under the same test conditions?"

Nobody uses it, then everybody uses it, the suddenly an entirely new sensor is miraculously found that does it all. ... and then I'm keeping track of three sensory outputs.

So you're saying you can use “#if 0”, but you cannot use “#if TEST_MACRO”? I'm confused.

Also, VCS is your friend, delete what is not needed at given time, and bring it back if it later is needed again.

No I could do that if it were my choice, it isn't.

I am saying that ultimately when they ask me to support "either or" as a configuration option, that preprocessor directives are useless at that point because all code will need to be included in the final result. And then further when they ask me to have parallel processes or threads talking to both sensors; recording the data from both at the same time so they can run a field test and compare the data - once again preprocessor directives are a moot point. In fact, in those situations, the "either or" case is a minor headache, the "both at the same time" case is an architectural expansion where I have to write a lot more code; also fully knowing that eventually much of it will be going away ... until someone long in the future says "You know ... we were getting better readings way back when we were using the <blah-blah> sensor ..." So a lot of this is the "R" part of R&D.

In thinking a bit further though on #if 0 versus #ifdef _SOME_WORDS_; I actually do not prefer unclear words for the reason that I see _TEST_MACRO_ or something like that and then I have to FIGURE OUT if that is ever declared. That's inconvenient. #if 0 is 100% clear, "This code is NOT included in the compilation".

I have a colleague who uses #ifdev _NEVER_ where they have #define _NEVER_ 0 somewhere. Yeah ... cool.

I don't mind that you choose to do what you do, please don't worry about my style. But like I say, this brief discussion has made me realize that I do like #if 0 because it is clear as to its intention.

Back to /* */ pair .v. //

/* */ pairs permit comments to spread over more than one line.
Unless that is you prefer a long, loopy winding, wrapped around line where the entire comment is only visible if you have set your editor to wrap lines).

So it is more useful to comment out entire chunks of code or text spread over many lines with one pair. (in // you would have to comment out each and every line and god help you in debugging if you forgot one line and more specially if you had to revert back after testing and forgot one line).

Also old c compilers may not permit //.

On the flip side, /* */ type comments within comments don't always work correctly. (// has eliminated the problem).

My choice : use both appropriately.

OK

What happens if you comment #defines?

#define FIELD_VALUE CONSTANT_NUMBER // no closing semi colon
.v.
#define FIELD_VALUE CONSTANT_NUMBER /* no closing semi colon */

if( DataValue == FIELD_VALUE )

OK

Nothing. They behave as you'd expect.

I expect that using // would comment out everything including the closing right bracket and anything that follows.

What I was trying to say is that the /* .. */ pair works with #define while // does not.

OK

The preprocessor does not treat the comment as part of the define or in other words the preprocessor removes the comment before
parsing the define and adding it to the compiler's symbol table

Ah, then sorry, it behaves the opposite way to what you'd expected.

In other words, // and /* … */ work the very same way in the example you've shown. As smeezekitty described, comments are stripped prior to having the macro added to the table of available macros.

Closing right bracket where? Put your code in [code][/code] brackets, and put in actual code, because whatever you wrote in your earlier post is not "code", the .v. is meaningless and would cause a syntax error. Your IF statement is irrelevant except in the fact that the definition you employed in it was not shown to be defined. Nor did you illustrate your point clearly.

The following code compiles without errors or warnings using gcc -Wall to compile it:

Preprocessor substitutions which have been assigned values are usable within the code for assignment and tests. Substitutions which have been defined to exist are usable within the code for tests.

And I do not believe that it is valid to code the following:

THAT will cause a compilation error stating that an expression was expected before the ')' on the if test line.

You're right. AFAIR, #ifdef, #else and #ifndef are used for this.

And as you said earlier, the complier seems to strip all comments from #defines.

OK