Monday, December 05, 2005

Commenting of code

I was just wondering about commenting of code lately, how do you guys comment your code.

When I started to program everybody always told me to comment almost every little step, like

// open file
fhandle = fopen() ;

// read line-per-line of the file until eof
while(!feof(fhandle)) {
}


Anyways, lately I’ve become lazy and just programmed as the thoughts came to me, but then my manager visited my desk one day and notified me to start commenting my code thoroughly.

Since then I respected my “elders” and started coding by first writing all the steps as comments

// open file
// if file not exist do this, otherwise continue
// read line
// analyze line
// if junk do nothing, if not junk handle with care


and then filling in all the “code”

// open file
fopen()
// if file not exist do this, otherwise continue
if(!fread)
// read line
freadln
// analyze line
// if junk do nothing, if not junk handle with care
if(read == junk) blablabla

4 Comments:

At 11:33 PM, Blogger selsine said...

I usually don't comment every little step when I program, especially when it's obvious what is happening.

Instead I usually comment the intent of the code block.

I.e. //This code attempts to read information from a file.

 
At 4:22 PM, Blogger Seron said...

Comments that just repeat what the statement does are worthless.

Oh, and if you'rre coding in C or C++, "while(!feof(fhandle))" is almost always wrong.

 
At 6:59 AM, Blogger Guru said...

I code everything first, then go back and comment as I do my own personal code review for my first stage of refactoring.

I comment general areas.
// Declarations
string mAddress = string.Empty;
int mZip = 0;

I comment decisions throughly, though.

// if the zip code isn't 5 digits...
if (mZip.Length != 5)
{
// ... alert the user to the error
lblError.Text = "Blah Error Blah";
return;
}
// if it is...
else
{
// ... process the Address
ProcessAddress();
}

That's just me, though. It makes the boss types happy, though. It also makes team wide code reviews go more smoothly

 
At 2:30 PM, Blogger Arné Klopper said...

that was just for illustration purposes, and in PHP

 

Post a Comment

<< Home