Re: The Last Word on Comments (was Re: Hungarian notation)

[Sandy McPherson <sandy@wgs.estec.esa.nl>]

C is not by definition a write only language. The problem is that there
are too many write only C programmers.

tersity != incomprehensibility
verbosity != comprehensibility

I have seen code with no comments which you would have to be a raving
moron not to understand and on the other hand lots of verbose drivvle
like

	int i;  /* loop counter * /
	for ( i =0; i < maximum; i++ ) /* loop while i < maximum*/
		;

also, confusion exists between "readable to a C programmer" and readable
to a layman, or an Ada programmer for that matter e.g:.

	/* open the file called file_name */
	fd = fopen( file_name, "w" );
	/* check if the file was opened correctly */
	if ( fd == NULL )
		/* tell the user what went wrong opening file_name
		   by writing a diagnostic to the error stream */
		(void)fprintf( stderr, "Error opening %s:\n%s\n",
			       file_name, strerror( errno ) );
	else
	{
	    	/* do something useful */
		
	}

What value do the comments have for an experienced C programmer? None
I would suggest, not even for maintainability. But if a QA guy who is
by nature an Ada programmer were to read this he would probably need
the comments.

Comments are for increasing clarity, use them to explain what is not
obvious from your code and to document the reasons why the code looks
like it does (i.e. references to requirements, interface control, etc.)

For instance a function implementing a Simpson's rule should have a
comment like /* Simpson's Rule, see "My Favaourite Algorithms page 21"
*/ and if you program it neatly and readably no other comment should
really be necessary.

Let typists type and progarammers program. I can touch type, but I
cannot program or write letters at touch typing speeds, as for both
exercises I need to have more then my eyes and fingertips engaged.

-- 
Sandy McPherson	MBCS CEng.	tel: 	+31 71 565 4288 (w)
ESTEC/WAS				+31 527 68 1314 (h)
P.O. Box 299
NL-2200AG Noordwijk