#134498 - keldon - Fri Jul 13, 2007 1:02 pm
Reason I ask: Coding style test for a development team
So what are your thoughts on commenting? My view is that your project has a general outline of where to find things and where to start looking for particular areas.
Then each class details its general purpose and gives enough information to be able to use it (I like the JavaDoc style) plus the key methods. Each method (obviously) is well documented with more than enough details to know its limitations, use, blah blah and so on.
Now when it gets to the methods some people comment every line or logical stage. Their task was to correct errors and write the code as you would, so maybe I'm over thinking this and should just write it in my style.
They originally had everything in a single main method,
Which I have changed it to something more on the lines of...
And also added:
Maybe I'm over thinking this.
So what are your thoughts on commenting? My view is that your project has a general outline of where to find things and where to start looking for particular areas.
Then each class details its general purpose and gives enough information to be able to use it (I like the JavaDoc style) plus the key methods. Each method (obviously) is well documented with more than enough details to know its limitations, use, blah blah and so on.
Now when it gets to the methods some people comment every line or logical stage. Their task was to correct errors and write the code as you would, so maybe I'm over thinking this and should just write it in my style.
They originally had everything in a single main method,
| Code: |
| // ---------------------- //
// Standard Include Files // // ---------------------- // #include <stdlib.h> #include <stdio.h> // --------------------- // // Structure Definitions // // --------------------- // // Definition of a player typedef struct PLAYER { int id; char player_name[ 50 ]; double ability; double potential; }; // Function: main() // Purpose: Main function for the program void main( void ) { FILE *p_file; // File being read in from PLAYER *player; // Player stored in file // Open the file to read from p_file = fopen( "file.txt", "r" ); // Read out the player information fread( &player, sizeof( PLAYER ), 1, p_file ); // Print the players name to the screen printf( "%s\n", player->player_name ); } // main() |
Which I have changed it to something more on the lines of...
| Code: |
| /** Will create an example file (file.txt) with a single PLAYER entry */
void createExampleFile (){ PLAYER myPlayer; FILE *p_file; // initialize player with basic information myPlayer.id = 1; myPlayer.ability = 1.0; myPlayer.potential = 1.0; strcpy ( (char *)&myPlayer.player_name, "Alan Smith"); // open and write to file p_file = fopen ( "file.txt", "w"); fwrite ( &myPlayer, sizeof(PLAYER),1,p_file); fclose(p_file); } // createExampleFile () |
And also added:
| Code: |
| /**
id: Each player has a unique id number player_name: Can contain all names (first, middle names, surname) or any one of the three. If more than one is given the first is expected to be the first name and the last to the the surname. If one is given it is expected to be the surname. Players are referred to by the surname during play, and the first name is used to distinguish between players with the same name ability: in the range of 0-1, with 0 being poor and 1 being excellent potential: in the range of 0-1, with 0 being poor and 1 being excelelnt */ typedef struct { int id; char player_name[ 50 ]; double ability; double potential; } PLAYER; |
Maybe I'm over thinking this.