Comment Style

**Richard Heathfield** · Sep 24 '08, 03:35 PM

Re: Comment Style

polas said:

Afternoon all. I was just wondering about this point - I have
(generally) used // for commenting a single line in C, but from
looking at code other people have written it seems many use /* */
(which I only use if my comment will be over multiple lines) - does
one way have any advantages over the other, or is the style exactly
that, a question of style?

/* ADVANTAGES */

* C89-conforming
* doesn't break when a line wraps (eg on code posted to Usenet!)
* robust against line-splicing

/* DISADVANTAGES */

* a little on the wordy side - you have to remember to close it
* doesn't nest

// ADVANTAGES

* nests // like // this
* terse

// DISADVANTAGES

* not C89-conforming
* breaks when a line wraps (eg on code posted to Usenet)
* fragile against accidental line-splicing:
foo(); // do the foo thing to c:\our_director y\
bar(); // now *why* isn't this function working?

As you can see, the advantages of one turn out to be the disadvantages of
the other.

For Usenet, /* */ is the clear winner, simply because of the line-break
issue: // with this kind of comment, when you post a very long comment
line as part of code that you present in a Usenet article, the code no
longer compiles.

--
Richard Heathfield <http://www.cpax.org.uk >
Email: -http://www. +rjh@
Google users: <http://www.cpax.org.uk/prg/writings/googly.php>
"Usenet is a strange place" - dmr 29 July 1999

**Richard** · Sep 24 '08, 03:45 PM

Re: Comment Style

polas <nick@helpforce .comwrites:

Afternoon all. I was just wondering about this point - I have
(generally) used // for commenting a single line in C, but from
looking at code other people have written it seems many use /* */
(which I only use if my comment will be over multiple lines) - does
one way have any advantages over the other, or is the style exactly
that, a question of style?
>
Cheers,
Nick
>
----
Mesham Parallel Programming Language
www.mesham.net

/* is much better for several reasons */

The most important one is that you can enclose multiple lines should
they break due to a different word wrap setting. Frankly I also think it
looks better :-)

/***************
* Comment block
* great eh
***************/

**Ben Pfaff** · Sep 24 '08, 04:45 PM

Re: Comment Style

Richard Heathfield <rjh@see.sig.in validwrites:

For Usenet, /* */ is the clear winner, simply because of the line-break
issue: // with this kind of comment, when you post a very long comment
line as part of code that you present in a Usenet article, the code no
longer compiles.

Or perhaps you should just refrain from word-wrapping code that
you post to Usenet.
--
"Am I missing something?"
--Dan Pop

**vippstar@gmail.com** · Sep 24 '08, 05:35 PM

Re: Comment Style

On Sep 24, 6:06 pm, polas <n...@helpforce .comwrote:

Afternoon all. I was just wondering about this point - I have
(generally) used // for commenting a single line in C, but from
looking at code other people have written it seems many use /* */
(which I only use if my comment will be over multiple lines) - does
one way have any advantages over the other, or is the style exactly
that, a question of style?

// was introduced in C99.
/* */ was since C89.
It's also possible to comment out code with
#if 0
....
#endif

It's not just style - if your code doesn't use ANY other C99 feature
other than //, just replace them with /* */.

Lastly, it's possible to comment multiple lines with //

// comment\
Another comment

**Richard** · Sep 24 '08, 05:35 PM

Re: Comment Style

vippstar@gmail. com writes:

On Sep 24, 6:06 pm, polas <n...@helpforce .comwrote:

>Afternoon all. I was just wondering about this point - I have
>(generally) used // for commenting a single line in C, but from
>looking at code other people have written it seems many use /* */
>(which I only use if my comment will be over multiple lines) - does
>one way have any advantages over the other, or is the style exactly
>that, a question of style?

>
// was introduced in C99.
/* */ was since C89.
It's also possible to comment out code with
#if 0
...
#endif

It's also possible to crack an egg with a jack hammer. That way is truly
horrible. Primarily because if you scrolled to the middle of a huge
block in an editor which did not colour code commented out code using
your way then you would not/may not notice it was commented out.

>
It's not just style - if your code doesn't use ANY other C99 feature
other than //, just replace them with /* */.
>
Lastly, it's possible to comment multiple lines with //

Huh? Could you explain that.

>
// comment\
Another comment

--

**Malcolm McLean** · Sep 24 '08, 05:55 PM

Re: Comment Style

"Richard" <rgrdev@gmail.c omwrote in message news:

vippstar@gmail. com writes:

>It's also possible to comment out code with
>#if 0
>...
>#endif

>
It's also possible to crack an egg with a jack hammer. That way is truly
horrible. Primarily because if you scrolled to the middle of a huge
block in an editor which did not colour code commented out code using
your way then you would not/may not notice it was commented out.
>

The problem is that you might have comments in the code. Since comments
don't nest, the only option is the #if workaround.

Quite a few people don't put comments in function bodies for this reason.

--
Free games and programming goodies.

http://www.personal.leeds.ac.uk/~bgy1mm

**Keith Thompson** · Sep 24 '08, 06:05 PM

Re: Comment Style

Ben Pfaff <blp@cs.stanfor d.eduwrites:

Richard Heathfield <rjh@see.sig.in validwrites:
>

>For Usenet, /* */ is the clear winner, simply because of the line-break
>issue: // with this kind of comment, when you post a very long comment
>line as part of code that you present in a Usenet article, the code no
>longer compiles.

>
Or perhaps you should just refrain from word-wrapping code that
you post to Usenet.

How?

Word-wrapping can occur at any of several stages between you writing
an article and somebody else reading it. You can usually avoid it by
keeping your lines sufficiently short, but that can breaks for quoted
text.

--
Keith Thompson (The_Other_Keit h) kst-u@mib.org <http://www.ghoti.net/~kst>
Nokia
"We must do something. This is something. Therefore, we must do this."
-- Antony Jay and Jonathan Lynn, "Yes Minister"

**Richard Heathfield** · Sep 24 '08, 06:15 PM

Re: Comment Style

vippstar@gmail. com said:

<snip>

It's also possible to comment out code with
#if 0
...
#endif

Nit: #if is not a comment syntax. It's a conditional compilation
preprocessor directive. It is therefore ideal for temporarily disabling
blocks of code during development or debugging. The term "commenting out"
is a hangover from languages that don't have conditional compilation, thus
forcing their users to abuse the humble comment when disabling code.

--
Richard Heathfield <http://www.cpax.org.uk >
Email: -http://www. +rjh@
Google users: <http://www.cpax.org.uk/prg/writings/googly.php>
"Usenet is a strange place" - dmr 29 July 1999

**Keith Thompson** · Sep 24 '08, 06:45 PM

Re: Comment Style

Richard<rgrdev@ gmail.comwrites :

vippstar@gmail. com writes:

[...]

>Lastly, it's possible to comment multiple lines with //

>
Huh? Could you explain that.

Read on.

>// comment\
>Another comment

And there's the explanation.

Splicing of lines ending in \ occurs before comments are processed.
In translation phase 2, the two lines physical source lines quoted
above are spliced into a single logical source line:

// commentAnother comment

In translation phase 3, the comment is replaced by a single space
character.

*But* that's a truly horrible way to do a multi-line comment, and I
hope that vippstar was joking. The trailing backslash can easily be
missed. Furthermore, if the backslash is followed by a space
character, which is even easier to miss, the splicing is not done.
(IMHO this is a flaw in the language definition; a backslash followed
only by whitespace should be treated as a trailing backslash.)

Of course, it's trivially easy to comment out multiple lines using //:

// comment
// Another comment

and most text editors will let you replace the beginning of each of
a range of lines with "//", or delete "//" over a range of lines,
fairly easily.

It's often suggested that #if 0 ... #endif is a better way to
comment out large blocks of code. It's certainly better than
/* ... */, since that style of comment doesn't nest. But if the
block is very large, it can be hard to tell at a glance when you're
looking at the middle of the block that it's been commented out.
(Yes, some editors do color highlighting that can help with this,
but not all do -- and, personally, I don't really like color
highlighting.)

My suggestion: If you want to comment out a block of code, insert
"#if 0" at the start and "#endif" at the end *and* insert, say,
"*" at the beginning of each line.

Or you can use "//", but only if the code will never be used with
compilers that don't support "//" comments.

--
Keith Thompson (The_Other_Keit h) kst-u@mib.org <http://www.ghoti.net/~kst>
Nokia
"We must do something. This is something. Therefore, we must do this."
-- Antony Jay and Jonathan Lynn, "Yes Minister"

**jameskuyper@verizon.net** · Sep 24 '08, 07:55 PM

Re: Comment Style

polas wrote:

Afternoon all. I was just wondering about this point - I have
(generally) used // for commenting a single line in C, but from
looking at code other people have written it seems many use /* */
(which I only use if my comment will be over multiple lines) - does
one way have any advantages over the other, or is the style exactly
that, a question of style?

/* */ works on both C89 compilers and C99 compilers
// works on C99 compilers, but it only works on some C89 compilers as
an extension. However, finding compilers which support that extension
is a lot easier than finding fully comforming implementations of C99.

"/*" makes everything that follows it a comment, up until the next */"
combination. This can be dangerous if you forget to type the
corresponding "*/", or mis-type it as "/*". The result is usually a
flood of error messages from the compiler; but the really dangerous
case is when the result produces no error messages; it just makes your
program malfunction.
"//" comments stop at the end of the line, which avoids that problem.

For the same reason, "//" has to be repeated on every comment line of
a comment, which means that it takes up more space. However, it's
generally a good idea to use some kind of formating to make multi-line
comments stand out:

/* This is a multi-line comment,
* this is the second line of the comment.
*/

If you're going to do that anyway, it doesn't make much difference
whether you type " *" or "//":

// This is the first comment line.
// This is the second comment line.

Personally, I find the second form easier to read and separate from
the actual code; Ben Pfaff apparently disagrees.

Many newsreaders can get confused by lines containing "//", and will
sometimes merge them with the following lines. This can make code
using "//" comments very hard to untangle.

**Robert Gamble** · Sep 24 '08, 07:55 PM

Re: Comment Style

On Sep 24, 11:32 am, Richard Heathfield <r...@see.sig.i nvalidwrote:

polas said:
>

Afternoon all. I was just wondering about this point - I have
(generally) used // for commenting a single line in C, but from
looking at code other people have written it seems many use /* */
(which I only use if my comment will be over multiple lines) - does
one way have any advantages over the other, or is the style exactly
that, a question of style?

>
/* ADVANTAGES */
>
* C89-conforming
* doesn't break when a line wraps (eg on code posted to Usenet!)
* robust against line-splicing
>
/* DISADVANTAGES */
>
* a little on the wordy side - you have to remember to close it
* doesn't nest
>
// ADVANTAGES
>
* nests // like // this

I wouldn't call that nesting, that's just including the comment start
sequence inside a comment, if it really nested then the comment would
continue to the next line in your example.

Note that you can do the same with with C-style comments:
/* this /* is /* legal */

so I don't see how the C++-style comments have an advantage here.

--
Robert Gamble

**Ian Collins** · Sep 24 '08, 08:05 PM

Re: Comment Style

Richard wrote:

vippstar@gmail. com writes:
>

>On Sep 24, 6:06 pm, polas <n...@helpforce .comwrote:

>>Afternoon all. I was just wondering about this point - I have
>>(generally) used // for commenting a single line in C, but from
>>looking at code other people have written it seems many use /* */
>>(which I only use if my comment will be over multiple lines) - does
>>one way have any advantages over the other, or is the style exactly
>>that, a question of style?

>// was introduced in C99.
>/* */ was since C89.
>It's also possible to comment out code with
>#if 0
>...
>#endif

>
It's also possible to crack an egg with a jack hammer. That way is truly
horrible. Primarily because if you scrolled to the middle of a huge
block in an editor which did not colour code commented out code using
your way then you would not/may not notice it was commented out.
>

But no one leaves "commented out" code in for long, do they? Code will
only be conditionally compiled out during testing and restored before
the code is committed.

So the only person to scroll "to the middle of a huge block" will be the
person who conditionally compiled out the code. If you have a short
term memory issue, that's a topic for another group.

--
Ian Collins.

**Sjouke Burry** · Sep 24 '08, 08:35 PM

Re: Comment Style

Ian Collins wrote:

Richard wrote:

>vippstar@gmail. com writes:
>>

>>On Sep 24, 6:06 pm, polas <n...@helpforce .comwrote:
>>>Afternoon all. I was just wondering about this point - I have
>>>(generally ) used // for commenting a single line in C, but from
>>>looking at code other people have written it seems many use /* */
>>>(which I only use if my comment will be over multiple lines) - does
>>>one way have any advantages over the other, or is the style exactly
>>>that, a question of style?
>>// was introduced in C99.
>>/* */ was since C89.
>>It's also possible to comment out code with
>>#if 0
>>...
>>#endif

>It's also possible to crack an egg with a jack hammer. That way is truly
>horrible. Primarily because if you scrolled to the middle of a huge
>block in an editor which did not colour code commented out code using
>your way then you would not/may not notice it was commented out.
>>

But no one leaves "commented out" code in for long, do they? Code will
only be conditionally compiled out during testing and restored before
the code is committed.
>
So the only person to scroll "to the middle of a huge block" will be the
person who conditionally compiled out the code. If you have a short
term memory issue, that's a topic for another group.
>

Ha! I have come across programs, where 60-80 percent was commented
out.
When asking the author, he said it was because he might want to
use the pieces sometime....... ..
Yikes.

**Ian Collins** · Sep 24 '08, 08:35 PM

Re: Comment Style

Sjouke Burry wrote:

Ian Collins wrote:

>Richard wrote:

>>vippstar@gmail. com writes:
>>>
>>>On Sep 24, 6:06 pm, polas <n...@helpforce .comwrote:
>>>>Afternoon all. I was just wondering about this point - I have
>>>>(generall y) used // for commenting a single line in C, but from
>>>>looking at code other people have written it seems many use /* */
>>>>(which I only use if my comment will be over multiple lines) - does
>>>>one way have any advantages over the other, or is the style exactly
>>>>that, a question of style?
>>>// was introduced in C99.
>>>/* */ was since C89.
>>>It's also possible to comment out code with
>>>#if 0
>>>...
>>>#endif
>>It's also possible to crack an egg with a jack hammer. That way is truly
>>horrible. Primarily because if you scrolled to the middle of a huge
>>block in an editor which did not colour code commented out code using
>>your way then you would not/may not notice it was commented out.
>>>

>But no one leaves "commented out" code in for long, do they? Code will
>only be conditionally compiled out during testing and restored before
>the code is committed.
>>
>So the only person to scroll "to the middle of a huge block" will be the
>person who conditionally compiled out the code. If you have a short
>term memory issue, that's a topic for another group.
>>

Ha! I have come across programs, where 60-80 percent was commented
out.
When asking the author, he said it was because he might want to
use the pieces sometime....... ..
Yikes.

Someone should have mentioned source control to him.

--
Ian Collins.