Comments: love/hate relationship
While browsing the blogosphere, I found a few other folks talking about code commenting. I'm always told by the person in charge, "Comment your code! It's the number one most important thing to do in a project!!!" In college, in a C++ class, my teacher said to comment EVERY line of code. "If you're going to set a variable, say what the variable is, why you're setting it, and how you got the value you're setting it to." He was a fan of one letter variable names, maybe to support his super commenting. He'd like this... I'm glad he was fired...
r = 10;
/* p is the constant pi, rounded to 5 decimal places. Pi is a ratio of the circumference to the diameter of a circle is the same for all circles. */
p = 3.14159;
/* a is the area of the circle with a radius equal to the value r, which is set above. To compute the area, multiply Pi by the square of the radius. To compute the square of r, multiply it by itself. */
a = p * r * r;
Well that's just silly :)
A lot of the focus for why to comment code is on "future developers reading your code". Well what if that future developer is you? I just ran into this. I had to make changes to my first big Flex app, which was 16 months and just as many coding methodologies ago. It's embarrassing to tell the client, "Sorry, this'll take a bit longer, this code is garbage." My old code was compressed into as few lines as possible, with bad function and variable names, bad use of white space, with IF statements three screens long.
I agree with Brian Kotek's thoughts on commenting code (link below). Comments are needed for so-so code. But really great code should be readable on its own. If you have 20 lines of code to accomplish something you can sum up in one sentence, there's a place for a comment. But I'm not going to put in comments such that the department secretary can understand what my code's doing.
And no more do we need the block of comments on the top of a file, saying the file name, who made it and when, and a history of who made what changes. Just look at the filename and through your version control system to see changes.
http://www.exmsft.com/~hanss/badcode.htm