Quote:
I've never really understood why some people get majorly obsessive about commenting code . . Generally speaking, your code should speak for itself, if it isn't then there's something wrong somewhere
I comment pretty obsessively. In fact, usually I write the comments first and then the code later. This is two-fold for me- first it helps me understand what I'm trying to do later when I (or another programmer) come back to look at it, and second it helps me make sure I've got it straight in my mind before I code it. If I can't explain something, then I'm not ready to write the code yet.

I understand about the code speaking for itself, but most of the time code can really only speak about the HOW, not the WHY.

Consider the following code:
Code:

for (i=0; i<Accounts.Count; i++)

{

  Accounts[i].Process();

}


This seems farily straightfoward code, so a comment like "//Loop through our accounts and process them" is not useful. We can see that from the code. However, a comment telling us what the real-world problem is that we're trying to solve is helpful in understanding the bigger picture: "//Calculate new monthly values for each of our accounts based on current market values".

Steve McConnell talks about this in his "Code Complete" book where you should try not to include low-level programming concepts (records, variables, etc.) in your comments but rather talk about real world problems (account, monthly statement, etc.).

I think you can get away with a few high level comments to explain what you're doing, but because I generally tend to write the comments first and describe the process, I end up with many comments sprinkled throughout. I don't think that level is necessary, but I don't think it's a bad thing, either. It's one of those habits that I've found helps me write more robust code.


Edited by JeffS (16/10/2005 21:39)
_________________________
-Jeff
Rome did not create a great empire by having meetings; they did it by killing all those who opposed them.