[tennesseekevin]

Not my personal style. I know I'm a nerd and there isn't much that can be done, but I'd love to hear your comments on my coding and commenting style. It'd be a great help to this newbie.

Clicking this will start a download of a text file called distance.c.
distance.c

Thanks,
Kevin

[Arkham_c]

Your coding style seems fine (different from mine, but fine). Coding style is not that important, other than that you should always strive to be consistent. Name your variables, methods, etc using consistent conventions that work for you. When you go to work professionally, there will often be a coding standard, and you'll need to abide by it.

I don't comment as heavily as you do, but that comes with experience. I generally feel that code should be self-commenting. All code comments should detail the purpose of a method or section, not the details thereof. If you can't figure out the how when you know the what, you are dealing with badly-written code.

An example:

Code:
/*
 * The next part actuall computes the distance using the pythagorean theorem.
 * In this case, length squared plus height squared equals distance squared.
 * The first 2 lines establishes the values of length and height. The last line
 * computes the distance between the points.
 */
	length = point_2_x - point_1_x; /* Gives the horizontal distance between points. */
	height = point_2_y - point_1_y; /* Gives the vertical distance between points. */
	
	distance = sqrt( ( ( length * length ) + ( height * height ) ) ); /* Gives the distance. */
	
/*
 * Print the distance.
 */
	printf( "The distance between %.0f,%.0f and %.0f,%.0f is %.1f.\n", point_1_x, point_1_y, point_2_x, point_2_y, distance );

The comments on pythagorean theorem would probably stay, but the details I would reduce. The "print the distance" comment is pretty pointless, when the next line is obviously a printf beginning with "The distance ...".

I would reduce it to this:

Code:
/*
 * The next part computes the distance using the pythagorean theorem.
 * length squared plus height squared equals distance squared.
 */
    length = point_2_x - point_1_x;
    height = point_2_y - point_1_y;
    distance = sqrt( ( ( length * length ) + ( height * height ) ) );

    printf( "The distance between %.0f,%.0f and %.0f,%.0f is %.1f.\n", 
            point_1_x, point_1_y, point_2_x, point_2_y, distance );

[tennesseekevin]

Thanks! I'm currently working my way through Practical C Programming and am using Steve Oualline's style. I agree with you in that I'm over-commenting, but I'm a little gunshy about a lack of information. I'm currently trying to figure out the software that we use at work to control our automation system. It's uncommented and made more difficult by the use of a lot of gotos that only reference line numbers, so it's difficult to keep the looping straight. I suppose good style will come with time.

Cheers, and I welcome any more thoughts and critiques.

Kevin

[Catfish_Man]

Originally posted by tennesseekevin:
Thanks! I'm currently working my way through Practical C Programming and am using Steve Oualline's style. I agree with you in that I'm over-commenting, but I'm a little gunshy about a lack of information. I'm currently trying to figure out the software that we use at work to control our automation system. It's uncommented and made more difficult by the use of a lot of gotos that only reference line numbers, so it's difficult to keep the looping straight. I suppose good style will come with time.

Cheers, and I welcome any more thoughts and critiques.

Kevin

In general, I've found that overcommenting is better than undercommenting. I've sorta gotten out of the habit of comments, and I'm having to force myself back into it now that I'm working with another person.

[K++]

I only have onse issue with this code. Wrong type of comments in some palces and not enough in others.

For the single line comments you should definetely be using \\.


For the method comment blocks, you should also include the purpose of the method, the date created, each variable passed to it, the type returned and the purpose of the type returned.

For voids you can cut down on alot of it but it should still be there.

A quick reformat would have it looke like:

Code:
/***************************************************************************** 
 *                                                                           *
 *	Distance - Compute the distance between two points.                      *
 * 	Author: Kevin Ford                                                       *
 *      Date Created: A Long Time Ago						 *
 * 	Purpose: Takes 2 Cartesian Co-ordinate points and give distance.         *
 * 	Usage: ./distance "X,Y"                    				 *
 *                                                                           *
 ****************************************************************************/

#include <stdio.h>
#include <math.h>

//These 2 lines allocate arrays for the storage of user input.

char input_array_1[ 5 ]; 	// Array for the first point.
char input_array_2[ 5 ]; 	// Array for the second point.

//These are the variables into which each point's X and Y value are scanned.

float point_1_x; 		// Value of the first point's X value.
float point_1_y; 		// Value of the first point's Y value.
float point_2_x; 		// Value of the second point's X value.
float point_2_y; 		// Value of the second point's Y value.

// These variables are used to compute the value of the distance.

float length; 			// Variable to hold the distance between the x values.
float height; 			// Variable to hold the distance between the y values.
float distance; 		// Variable to hold the computed distance value.


/*****************************************************************************
 *                               Main function    .                           *
 *****************************************************************************/
 
int main() {
 
	// Ask User for input.

	printf( "This program calculates the distance between two given points.\n" );
	printf( "Use the format \"X,Y\" to enter the points.\n" );
	printf( "Please enter the first point: " );


	// Get the keys pressed and store the values in input_array_1. Then,
	// scan the values into point_1_x and point_2_y.

	fgets( input_array_1, sizeof( input_array_1 ), stdin );
	sscanf( input_array_1, "%f,%f", &point_1_x, &point_1_y );

	// Asks for the second point, store the value in input_array_2 and scan
	// them into point_2_x and point_2_y.

	printf( "Please enter the second point: " );
	fgets( input_array_2, sizeof( input_array_2 ), stdin );
	sscanf( input_array_2, "%f,%f", &point_2_x, &point_2_y );
	
	// The next part computes the distance using the pythagorean theorem.
	// length squared plus height squared equals distance squared.

    	length = point_2_x - point_1_x;
    	height = point_2_y - point_1_y;
    	distance = sqrt( ( ( length * length ) + ( height * height ) ) );

    	printf( "The distance between %.0f,%.0f and %.0f,%.0f is %.1f.\n", 
            	point_1_x, point_1_y, point_2_x, point_2_y, distance );
	
	return 0;
}

Couple things:
1) I line up assignment comments for easy reading and clarity.
2) // is liess characters than \* *\
3) No need for "this line does" since all comments will refer to upcoming lines
4) Should also be in present or future tense.


Lastly comment stlye is a personal thing, I am anal about it, and have lots of nuances to the way I both comment and format my code, its from lots of time coding and wanting it to be clear and concise.

Note: the vbulletin is breaking the long *** in wierd ways pretend they are both 1 line.

[ambush]

Originally posted by tennesseekevin:
Not my personal style. I know I'm a nerd and there isn't much that can be done, but I'd love to hear your comments on my coding and commenting style. It'd be a great help to this newbie.

Clicking this will start a download of a text file called distance.c.
distance.c

Thanks,
Kevin

It's a bit "overkill" if you ask me.

Too much *********** everywhere.
This stil is imho rotten.

ASCII star rectangles suck
just do something � la ProjectBuilder:

Code:
//
//  SMController.h
//  Chercher
//
//  Created by Olivier Lanct�t on Sun Sep 14 2003.
//  Copyright (c) 2003 Clich� Software. All rights reserved.
//
// A random desc.

Also, you comment way too much.
It's a bit of a waste of time if you're not going to open source your code. And even if you did, comment less.

Example:

Code:
/*
 * Print the distance.
 */
printf(whatever);

It's not like we don't know what printf does

Instead of using ***** rectangles, you could use

Code:
#pragma mark -
#pragma mark IBActions
#pragma mark -

It's a lot neater.

The style you use is wayyyy to C-Book like.. way to O'reilly ish

Don't comment that much.

[ambush]

Originally posted by tennesseekevin:
Thanks! I'm currently working my way through Practical C Programming and am using Steve Oualline's style. I agree with you in that I'm over-commenting, but I'm a little gunshy about a lack of information. I'm currently trying to figure out the software that we use at work to control our automation system. It's uncommented and made more difficult by the use of a lot of gotos that only reference line numbers, so it's difficult to keep the looping straight. I suppose good style will come with time.
Kevin

I thought Mr. Oualline was anti-goto?

[Chuckit]

Originally posted by ambush:
I thought Mr. Oualline was anti-goto?

I somehow doubt Steve Qualline wrote the automation software his employer uses....

[Arkham_c]

Originally posted by Catfish_Man:
In general, I've found that overcommenting is better than undercommenting. I've sorta gotten out of the habit of comments, and I'm having to force myself back into it now that I'm working with another person.

The biggest problem with over-commenting is that over time, the code gets updated, but the comments do not. Then you have code that no longer works as the comments suggest. This is worse than no comments at all.

There was a fairly in-depth discussion on comments recently on the RB DR-NUG mailing list. If you're interested, you could read the archives.

[Brass]

I always thought that for comments in C, the "/*" and "*/" were the only official type of comments for ANSI C and that the "//" (single line) comments were only introduced with C++ and other C derivatives (including Objective-C).

If that is the case, "//" comments may be inappropriate (depending on the potential end uses of the code) as it may not compile on some systems. Only use "//" if you're sure that the code will only ever be compiled with a compiler/preprocessor that knows to ignore them as comments. They're certainly fine with Project Builder and the compiler bundled with OS X.

However, C code with "//" comments do not compile on some of the Solaris systems here, unless we specifically use a C++ compiler. Admittedly this is probably a very rare case these days, but it's something to be aware of.

[Brass]

Originally posted by Brass:
I always thought that for comments in C, the "/*" and "*/" were the only official type of comments for ANSI C and that the "//" (single line) comments were only introduced with C++ and other C derivatives (including Objective-C).

Aha, I was right... I just found the following, in a Google search:

C and C++ Comments

[Chuckit]

That's actually not true anymore. // isn't a valid comment delimiter in ISO C89, but the newer C99 standard allows it.

[tennesseekevin]

Originally posted by K++:

Couple things:
1) I line up assignment comments for easy reading and clarity.

Can you give me an example of such?

I somehow doubt Steve Qualline wrote the automation software his employer uses....

I certainly wish Steve worked at Cirque. Life would be much simpler.

Again, I thank you all. Any links I should look at for more info on coding style? Google's turned up a bunch of them, but I imagine personal style is like an opinion. Sorting out the good one's can be tough. I'm thinking about looking at Code Complete after I finish Practical C. Any other books to look at on the intermediate level?

Cheers,
Kevin

[Brass]

Originally posted by Chuckit:
That's actually not true anymore. // isn't a valid comment delimiter in ISO C89, but the newer C99 standard allows it.

Well it's still true that it will fail on some systems with a syntax error. So although such instances would be very rare, I'm just saying that it's something to be aware of, if you're planning on making the code portable - you'll need to be certain that all your target systems will have the required versions of the compiler.

[calumr]

Originally posted by tennesseekevin:
[B]Can you give me an example of such?

When you have variables that are different lengths, it is easier to read if you line up everything after the '=':

Code:
shortVar1 = 1;
shortVar2 = 3.14159;
myVeryLongVarName = 42;

vs

Code:
shortVar1         = 1;
shortVar2         = 3.14159;
myVeryLongVarName = 42;