One more point regarding = and == (more flamage)

[Blair P. Houghton]

In article <20107 at alice.att.com> ark at alice.UUCP () writes:
>In article <3182 at inews.intel.com> bhoughto at pima.intel.com (Blair P. Houghton) writes:
>> Put [comments] in, and make
>> them accurate, and it doesn't matter how much the code obfuscates.
        ^^^^^^^^

I said accurate.  I'm sure I did.

>Not everyone agrees that comments should explain what code does
>on a line-by-line level.

That depends (not the agreeing; the line-by-line-ness).  If it's
a yacc source (the .y file), every line gets a comment, since there's
often little else in the structure to indicate what j.random.variable
means, when it's stuffed in an action.  Comments shouldn't be
things like

       /*
	*  fleem the list
	*/

	/* assign a to be and check against zero */
	if ( a=b )...
	    /* nonzero; loop */
	    for( c = b; c; c = c->next )
		b = fleem(c);	/* fleem until charged */
	else
	    /* zero */
	    ...

They should be things like

       /*
	*  fleem the list
	*/

	/* keep a pointer to the head of the list for fleem() to use */
	if ( a = b )
	    /* the head of the list exists; look for the tail */
	    for( c = b; c; c = c->next )
		b = fleem();	/* fleem until charged */
	else
	    /* no head; start a list */
	    ...

whereas

       /*
	*  fleem the list
	*/

	if ( (a=b) != 0 )
	    for( c = b; c != 0; c = c->next )
		b = fleem(c);	/* fleem until charged */
	else
	    ...

Doesn't tell me the first thing about the use of a.

>The trouble is that if a comment restates
>what an obvious piece of code does, then it's just clutter -- and
>if it says something different from the code then something is
>seriously wrong.

And if the code is a collection of identifiers and operators,
the comments can't help saying something different.

Since nobody I know of, except device-driver writers (and maybe
Chris Torek) thinks in terms of bytes and pointers (it's
objects and references to the real world, even if people tend
to use the terms "bytes" and "pointers", which are metaphorical
terms they generally do not understand the true meaning of),
every token in a piece of non-systems code has a semantic
meaning far above its syntactic effects.

>People bring me a lot of broken programs to help fix.  The first
>thing I do when looking at such a program is to cover up the
>comments and insist that the author not attempt to explain the
>program to me.  All too often the bug has been that the code
>misstated the author's intent, although that intent was correctly
>stated in the comments.

That can be done no matter how clearly the code states
intent, as well.  It's called stupidity, and no amount
of adherence to the style guide will save you from it.

>Stragetic comments are extremely important: ``this section ensures
>that database X reflects the changes made to database Y.''  Tactical
>comments, however, are sometimes of negative worth.
>
>As to the original question, I stand by the recommendation I
>made in `C Traps and Pitfalls:' if you have an assignment as
>the top-level operator in a test, such as if(a=b), rewriting it
>as if((a=b)!=0) will make your intentions obvious in a way that
>the original never will.

My intentions are always obvious.  If I put two of these: `=',
it's a relational operator; if I put one, it's an assignment.
If I meant something other than what I typed, it's a bug.
So is:

       /*
	*  fleem the list
	*/

	if ( (c=b) != 0 )
	    for( a = b; a != 0; a = a->next )
		b = fleem(a);	/* fleem until charged */
	else
	    ...

Big help, those zeroes...

				--Blair
				  "Just today someone showed me
				   '{static int foo=0; ... if (foo=0)...}'
				   and I needed neither a comment
				   nor the lack of a '!=0' to tell
				   me what was wrong, two seconds after
				   it hit the screen..."