Commenting C & C++ code

[Structural Integrity]

How do you comment your C and C++ (or any similar) code? I'm wondering because I don't have a generic way of doing this myself.

Any tips?

TY

[Gayle29uk]

/*************************************************
* Function:  foo                                 *
* Use:  What the hell it's used for.             *
* Description of arguments goes here.            *
* Variable list in here.                         *
* Notes:  Specific things to point out (if any). *
*************************************************/

int foo (char bar)
{
}

No comments in functions themselves, if the code needs it it's too complex for easy maintenance.

[Nodrog]

A line or two before any functions that dont have obvious names to explain what they do, and a single line comment next to any variable that isnt used for something obvious.

[djbass]

What's the point in writing illegible code if you're going to explain it all to them?

=[DJ Bass]=

[Gayle29uk]

Originally posted by djbass
What's the point in writing illegible code

All jokes about 'job security' aside, legible code is almost always better. I've just written a PHP interface for some DB related bits at work and I could have made the code twice as efficient and half the size. I didn't because in it's current form it's easy for someone else to modify at a later date and the difference between a runtime of 50 microseconds and 25 microseconds doesn't really matter to anyone.

[Structural Integrity]

Originally posted by Gayle28uk
All jokes about 'job security' aside, legible code is almost always better. I've just written a PHP interface for some DB related bits at work and I could have made the code twice as efficient and half the size. I didn't because in it's current form it's easy for someone else to modify at a later date and the difference between a runtime of 50 microseconds and 25 microseconds doesn't really matter to anyone.

Yes it does... to my kind of applications. 1 frame per second more on YOUR machine is definately something to aim for, as it can have quite and impact on playability and thus a bigger audience.

If only I could get my profiler to work I'd look how I can speed my app up.

[Gayle29uk]

Originally posted by Structural Integrity
Yes it does... to my kind of applications. 1 frame per second more on YOUR machine is definately something to aim for, as it can have quite and impact on playability and thus a bigger audience.

If only I could get my profiler to work I'd look how I can speed my app up.

I said almost always. I've written self modifying code to save execution cycles before now but if it's not necessary you don't do it. If you do you document it

[Raging.Retard]

Last time I checked Gayle, you were in support? Not development?

'No comments in functions themselves, if the code needs it it's too complex for easy maintenance'

To be honest, thats just crap. I pity you if the day ever comes when someone calls you at 4 in the morning saying 'blah blah' has broken can you fix it. Its bad enough if its your own code, but even worse if its someone else's.

Lack of comments in code gets right on my tits.

Also, what is the case if the code is complex? There will always be instances (unless your only doing trivial things) where the code can get compilcated. Always remember that whatever you write, it will be 10 times more compilcated for someone else to alter.

As a result I tend to comment fairly heavily, most people wont like my notation mind as I use Hungarian notation, but heres an example snippet from a recently used method.

/////////////////////////////////////////////////////////////////////////
// Initialise And Connect To DB

// Open Databse Connection
SqlConnection objConnection = new SqlConnection(ConfigurationSettings.AppSettings["SQLConnection"]);
objConnection.Open();
			
/////////////////////////////////////////////////////////////////////////
// Validate User Login
			
// Create Command Interface
SqlCommand cmdStoredProc = new SqlCommand("db_CheckLogin", objConnection);
cmdStoredProc.CommandType = CommandType.StoredProcedure;
// Fill The Parameters Collection Based Upon Stored Procedure.
SqlParameter workParam = null;
workParam = cmdStoredProc.Parameters.Add("@LoginName", SqlDbType.Char, 15);
workParam = cmdStoredProc.Parameters.Add("@Password", SqlDbType.Char, 15);
// Prepare Output Parameter
workParam = cmdStoredProc.Parameters.Add("@ReturnCode", SqlDbType.UniqueIdentifier, 16);
workParam.Direction = ParameterDirection.Output;
// Set Values For Our Procedure
cmdStoredProc.Parameters["@LoginName"].Value = ctrlUsername.Text;
cmdStoredProc.Parameters["@Password"].Value = ctrlPassword.Text;
// Exec Procedure
cmdStoredProc.ExecuteNonQuery();

/////////////////////////////////////////////////////////////////////////
// Next Thing .... etc etc

[Gayle29uk]

Originally posted by Raging.Retard
Last time I checked Gayle, you were in support? Not development?

I do work in support but it's by choice. My university course was systems analysis/programming oriented though, I will however admit to not having developed any commercial apps so my commenting tends to be enough for someone who knows what they're doing but not enough for a beginner.

[Raging.Retard]

Originally posted by Gayle28uk
I do work in support but it's by choice.

Appologies, it wasnt my intent to belittle your choice of employment, but to query the origin of your opinions.

[Gayle29uk]

Originally posted by Raging.Retard
Appologies, it wasnt my intent to belittle your choice of employment, but to query the origin of your opinions.

No worries, looking around at my fellow supprot peeps 90% of them wouldn't know what gcc even stood for I simply meant to state that while I chose tech support over development I still know one end of a compiler from the other, I do admit my lack of commercial coding experience though.

[edit] Apparently I don't know what GCC stands for either but my point still stands [/edit]

Gnu C Compiler ?