Comments INSIDE statements - valid ??

Go To Last Post
25 posts / 0 new
Author
Message
#1
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

While Googling about multi-line C statements I came across comments inside a statement and was wondering if that is valid coding. I Googled specifically for this but didn't immediately get related results.

 

Example:

 

if ( var1 /*this var is for blah blah*/  ==  var2 /*and this var is for blah blah*/ )
/*then this is what happens*/
{
    // code
}

Never really had a need to do this but it did stir my curiosity.

 

Keith.

 

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Of course it's valid. What would not be valid if you used C++ style "//" comments as the line effectively ends once that is encountered.

 

When debugging I'll often turn off a conditional in a multi condition if() by turning off some part with /*... */ commenting.

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Thanks Cliff,

 

just wanted to be sure.

 

I also often comment out parts of my code when debugging but I just wasn't sure if you could put a comment smack bang in the middle of a statement as I showed in my example.

 

Keith.

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

A comment is allowed anywhere that whitespace is allowed.

 

And remember: apart from where necessary to separate tokens, 'C' completely ignores whitespace.

 

if(var1==var2){some_expression};

is equivalent to

if
(
var1
==
var2
)
{
some_expression
}
;

and

if
   (
      var1
         ==
            var2
               )
                  {
                     some_expression
                        }
                           ;

In fact, one of the first things that the preprocessor   does is to remove comments and collapse all whitespace sequences to a single space

 

GCC preprocessor documentation wrote:

1.1 Transformations Made Globally

Most C preprocessor features are inactive unless you give specific directives to request their use. (Preprocessing directives are lines starting with `#'; see section 1.2 Preprocessing Directives). But there are three transformations that the preprocessor always makes on all the input it receives, even in the absence of directives.

 

  • All C comments are replaced with single spaces.

     

 

https://gcc.gnu.org/onlinedocs/g...

Top Tips:

  1. How to properly post source code - see: https://www.avrfreaks.net/comment... - also how to properly include images/pictures
  2. "Garbage" characters on a serial terminal are (almost?) invariably due to wrong baud rate - see: https://learn.sparkfun.com/tutorials/serial-communication
  3. Wrong baud rate is usually due to not running at the speed you thought; check by blinking a LED to see if you get the speed you expected
  4. Difference between a crystal, and a crystal oscillatorhttps://www.avrfreaks.net/comment...
  5. When your question is resolved, mark the solution: https://www.avrfreaks.net/comment...
  6. Beginner's "Getting Started" tips: https://www.avrfreaks.net/comment...
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Thanks very much Awneil.

 

Keith.

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

It's not only allowed, but is very common.  Especially within data initialization (this example is from the Arduino core):

const uint8_t PROGMEM digital_pin_to_port_PGM[] = {
	PD, /* 0 */
	PD,
	PD,
	PD,
	PD,
	PD,
	PD,
	PD,
	PB, /* 8 */
	PB,
	PB,
	PB,
	PB,
	PB,
	PC, /* 14 */
	PC,
	PC,
	PC,
	PC,
	PC,
};

 

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

It might be allowed but that doesn't mean it's a good idea.

#1 This forum helps those that help themselves

#2 All grounds are not created equal

#3 How have you proved that your chip is running at xxMHz?

#4 "If you think you need floating point to solve the problem then you don't understand the problem. If you really do need floating point then you have a problem you do not understand." - Heater's ex-boss

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Why is adding explanations of the code for the benefit of the reader/maintainer ever a bad idea?

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

clawson wrote:
Why is adding explanations of the code for the benefit of the reader/maintainer ever a bad idea?

 

Comments, in the right place, are an excellent idea. But when placed as in the OP's example I reckon the readability, and hence maintainability, goes down the pan.

#1 This forum helps those that help themselves

#2 All grounds are not created equal

#3 How have you proved that your chip is running at xxMHz?

#4 "If you think you need floating point to solve the problem then you don't understand the problem. If you really do need floating point then you have a problem you do not understand." - Heater's ex-boss

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Oh I thought you were saying it about westfw's code example which actually looks like most excellent documentation. 

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Brian Fairchild wrote:
when placed as in the OP's example I reckon the readability, and hence maintainability, goes down the pan.

Maybe.

 

If I have a multi-test 'if', I might well comment it something like

if( (something == otherthing ) ||  // What this condition means
    (thatthing >  somelimit  )  )  // What this condition means
{
   :
   :

(the stupid code editor made that unnecessarily hard to type - and then doesn't even give syntax highlighting angry )

Top Tips:

  1. How to properly post source code - see: https://www.avrfreaks.net/comment... - also how to properly include images/pictures
  2. "Garbage" characters on a serial terminal are (almost?) invariably due to wrong baud rate - see: https://learn.sparkfun.com/tutorials/serial-communication
  3. Wrong baud rate is usually due to not running at the speed you thought; check by blinking a LED to see if you get the speed you expected
  4. Difference between a crystal, and a crystal oscillatorhttps://www.avrfreaks.net/comment...
  5. When your question is resolved, mark the solution: https://www.avrfreaks.net/comment...
  6. Beginner's "Getting Started" tips: https://www.avrfreaks.net/comment...
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Agreed, the first example the OP posted will work but is not exactly good to look at for the coder code writer and especially the person maintaining the code 10 years from now (which coincidentally could also be the same person as the code writer).

 

The other two examples posted by awneil and westfw are good, real world examples. Unfortunately, what OP posted is real world... just not good haha

My digital portfolio: www.jamisonjerving.com

My game company: www.polygonbyte.com

Last Edited: Mon. Apr 17, 2017 - 08:24 PM
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

It's not clear if the OP example was supposed to be from actual code, or just a made-up illustration of the kind of thing being discussed.

 

Anyhow,

if ( var1 /*this var is for blah blah*/  ==  var2 /*and this var is for blah blah*/ )

does rather suggest that the variables are poorly named if they require such comments!

Top Tips:

  1. How to properly post source code - see: https://www.avrfreaks.net/comment... - also how to properly include images/pictures
  2. "Garbage" characters on a serial terminal are (almost?) invariably due to wrong baud rate - see: https://learn.sparkfun.com/tutorials/serial-communication
  3. Wrong baud rate is usually due to not running at the speed you thought; check by blinking a LED to see if you get the speed you expected
  4. Difference between a crystal, and a crystal oscillatorhttps://www.avrfreaks.net/comment...
  5. When your question is resolved, mark the solution: https://www.avrfreaks.net/comment...
  6. Beginner's "Getting Started" tips: https://www.avrfreaks.net/comment...
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Brian Fairchild wrote:
It might be allowed but that doesn't mean it's a good idea.

Amen 

"When all else fails, read the directions"

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 1

This might be slightly off topic but I have found it better to disable code using the #if 0 and #endif. Stops you from getting into trouble if you have /* */ in the section of code you want disabled.

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 1

Rather a lot of perfectly sensible comments are inside statements.

A function definition includes at least one compound statement, e.g. {}.

Also comments regarding struct and union members will usually be inside statements.

There is no reason comments regarding function parameters should not go inside the function header.

"Demons after money.
Whatever happened to the still beating heart of a virgin?
No one has any standards anymore." -- Giles

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

clawson wrote:

Why is adding explanations of the code for the benefit of the reader/maintainer ever a bad idea?

If the code needs to be explained, usually it's because the names used in the code are cryptic. 

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

clawson wrote:
Why is adding explanations of the code for the benefit of the reader/maintainer ever a bad idea?

It is certainly possible to place comments in such a way that they obscure the actual code!

 

And we know too well that not all "comments" add value.

 

But, in general, it is a very rare complaint that code has "too many" comments - I agree!

 

Top Tips:

  1. How to properly post source code - see: https://www.avrfreaks.net/comment... - also how to properly include images/pictures
  2. "Garbage" characters on a serial terminal are (almost?) invariably due to wrong baud rate - see: https://learn.sparkfun.com/tutorials/serial-communication
  3. Wrong baud rate is usually due to not running at the speed you thought; check by blinking a LED to see if you get the speed you expected
  4. Difference between a crystal, and a crystal oscillatorhttps://www.avrfreaks.net/comment...
  5. When your question is resolved, mark the solution: https://www.avrfreaks.net/comment...
  6. Beginner's "Getting Started" tips: https://www.avrfreaks.net/comment...
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 1

At various times I guess I have spent 10+ years of my life as a code maintainer. Having to wade in and fix faults in legacy code bases where the original author is long gone and the likelihood is that the original code's design data is missing/atrocious or unusable/unavailable for various reasons. So often all you have to go on are the local comments in the code. In this scenario - to my mind - there can never be enough detail. Obviously I don't mean gratuitous commenting:

int var = 7; // set var to be 7

but some generally useful stuff like:

int var = 7;  // the number of days in the week it will be active

and yes I agree that:

int active_days_in_week = 7;

could be "self documenting". But in my experience few programmers are this fastidious. They have a fear of long variable names or maybe the code was written for some ancient, mickey-mouse compiler that had artificial limits on such things.

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

I wrote:
It is certainly possible to place comments in such a way that they obscure the actual code!

But it's a lot easier to strip-out "excessive" comments than it is to work out missing details!

 

So, as Cliff says, it's a very rare complaint that there are "too many" comments!

 

But I think we have now diverged a long way from the actual topic of this thread - whether it is legal.

Top Tips:

  1. How to properly post source code - see: https://www.avrfreaks.net/comment... - also how to properly include images/pictures
  2. "Garbage" characters on a serial terminal are (almost?) invariably due to wrong baud rate - see: https://learn.sparkfun.com/tutorials/serial-communication
  3. Wrong baud rate is usually due to not running at the speed you thought; check by blinking a LED to see if you get the speed you expected
  4. Difference between a crystal, and a crystal oscillatorhttps://www.avrfreaks.net/comment...
  5. When your question is resolved, mark the solution: https://www.avrfreaks.net/comment...
  6. Beginner's "Getting Started" tips: https://www.avrfreaks.net/comment...
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

Once upon a time, I had a professor who named some nodes on a rooted tree.
Alas the names were not quite right.
Sometimes the names referred to nodes that did not exist.
Similar correct names would have been rather long.
For my own work, I renamed the nodes alpha through gamma
(the order was meaningful)
and used comments to provide correct definitions.

"Demons after money.
Whatever happened to the still beating heart of a virgin?
No one has any standards anymore." -- Giles

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

awneil wrote:

It's not clear if the OP example was supposed to be from actual code, or just a made-up illustration of the kind of thing being discussed.

 

Anyhow,

if ( var1 /*this var is for blah blah*/  ==  var2 /*and this var is for blah blah*/ )

does rather suggest that the variables are poorly named if they require such comments!

 

Just a made up illustration Awneil. To date I have never commented  code like that, but was curious if it was legal to do so.

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

And now you know!

 

laugh

Top Tips:

  1. How to properly post source code - see: https://www.avrfreaks.net/comment... - also how to properly include images/pictures
  2. "Garbage" characters on a serial terminal are (almost?) invariably due to wrong baud rate - see: https://learn.sparkfun.com/tutorials/serial-communication
  3. Wrong baud rate is usually due to not running at the speed you thought; check by blinking a LED to see if you get the speed you expected
  4. Difference between a crystal, and a crystal oscillatorhttps://www.avrfreaks.net/comment...
  5. When your question is resolved, mark the solution: https://www.avrfreaks.net/comment...
  6. Beginner's "Getting Started" tips: https://www.avrfreaks.net/comment...
  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

adam3141 wrote:

This might be slightly off topic but I have found it better to disable code using the #if 0 and #endif. Stops you from getting into trouble if you have /* */ in the section of code you want disabled.

+1

Four legs good, two legs bad, three legs stable.

  • 1
  • 2
  • 3
  • 4
  • 5
Total votes: 0

John_A_Brown wrote:

adam3141 wrote:

 

This might be slightly off topic but I have found it better to disable code using the #if 0 and #endif. Stops you from getting into trouble if you have /* */ in the section of code you want disabled.

+1

 

Just had a play and got to say - I'm converted.