Comment Styles

[RedSon]

So what do you guys use for headers to your files or headers for each individual method. If you write java don't respond to this thread.

Something like:

////////////////////////////////////////////////////////////////
// File: foo.cpp
// Description: Takes a snarbleblart and applies the merkalanium transform to output a booblenortrox.
// Author: RedSon
/////////////////////////////////////////////////////////////////
 
et cetra, et cetra....
 

[Ganon11]

Informally (as I'm only a high school student doing assignments for my teacher), my header looks something like

/* Chapter X, Exercise Y (or substitute for Exercise, as we may be working off of a handout)
Class Name (Independent Study), Name */

For some of my recent independent (read: fun) projects, I've bee adding a "Date last modified" section, a name, a brief description of the project and a mock "version".

For methods, I rarely comment, but when I do I include a brief description including what the function basically does, sometimes how it works, the postconditions and preconditions, and the return value - what it could be and what it specifies. So the comment might be (from my latest project, Chess):

// boolean whiteInCheck()
// whiteInCheck() loops through every possible space on board.
// If there is any piece that can legally capture the White King
// (it has 'line of sight' and is a Black piece), then the function
// immediately returns true.  If the loops finish, then no piece
// threatens the White King, and there is no check.  The function
// returns false.
// Pre-condition: board has been initialized to a 2D array of
//                chessPieces (8 x 8)
// Post-condition: Indicates whether the White King is in check.
// returns: boolean - True = White King in check, false = No check

[r035198x]

Informally (as I'm only a high school student doing assignments for my teacher), my header looks something like

/* Chapter X, Exercise Y (or substitute for Exercise, as we may be working off of a handout)
Class Name (Independent Study), Name */

For some of my recent independent (read: fun) projects, I've bee adding a "Date last modified" section, a name, a brief description of the project and a mock "version".

For methods, I rarely comment, but when I do I include a brief description including what the function basically does, sometimes how it works, the postconditions and preconditions, and the return value - what it could be and what it specifies. So the comment might be (from my latest project, Chess):

// boolean whiteInCheck()
// whiteInCheck() loops through every possible space on board.
// If there is any piece that can legally capture the White King
// (it has 'line of sight' and is a Black piece), then the function
// immediately returns true.  If the loops finish, then no piece
// threatens the White King, and there is no check.  The function
// returns false.
// Pre-condition: board has been initialized to a 2D array of
//                chessPieces (8 x 8)
// Post-condition: Indicates whether the White King is in check.
// returns: boolean - True = White King in check, false = No check

And how far are you with this one?

[Ganon11]

And how far are you with this one?

Close - very close. I finished the rules for Castling this morning, then I'll have to make slight changes to the Pawn type, and then testing begins.

[r035198x]

Close - very close. I finished the rules for Castling this morning, then I'll have to make slight changes to the Pawn type, and then testing begins.

You won't have to worry about where to get testers