[B-Con]

I personally have four reasons for writing comments. If a comment does not fall squarely into one of them, I try to omit it:

1) Why the code is doing what it's doing. What's the motivation? Why is a check necessary? What's the context?

2) High-level overview. 20 lines of code may speak for themselves, but a quick sentence can easily summarize it. I love well-summarized code. "Do X with the Y unless it's Z" is a really fast read. (Function names obviously provide this sort of explanation, but sometimes a name is not obviously not always sufficient.)

3) Stubs / future notes. Sometimes you need to leave something stubbed out. If you have thoughts on what they code will need to be, leave a note about it. This is easily removed later.

4) Quirks. If the code does something that is not obvious, note that. Non-obvious side-effects, bugs, etc. Don't discover something painful, then leave the next person (possibly a future you) to re-learn that same painful lesson.

Code does stuff. Comments describe the code. Comments should not re-describe what the code does, they should be about the code and the code's context itself.

[kondro]

3 & 4 are really the only two valid reasons to use comments, in my opinion.

1 & 2 are both better solved with method abstraction. Comments describing what code is doing is always a code-smell to me. If you have 20 lines of code that is non-obvious, think about extracting it to one or more well-named methods.

[katbyte]

his 1st point was not about commenting what code does but why it is done the way it is. I don't see how you can extract all the required information (including web links or rational) explain the rational behind a implementation into a function name.

    // unroll loop for 50% speed increase. Optimal offset 4
    // 3: 25%
    // 4: 50%
    // 5: 40%  
    for(i=0;i<x;i+=4) {
    ...
    }

How could you extract that into a function name?

2 is definitely more an opinion, but I use XML comments on every function, object, parameter, return value with a quick summery because it integrates into my IDE and is used to generate API and library documentation that is invaluable to developers who don't necessary have the code, only the documentation.

[kamjam]

I use XML comments on every function

I'm not talking about your opinion on point 2 here specifically, but your comment reminded me of a discussion I had with someone about comments... well, they were arguing (like the OP) that you should not use comments in your code but they would gladly use XML comments for the same reasons you have stated. So they would go to the lengths of helping out external developers with comments but not their own internal developers. Seemed very strange to me!

[kondro]

I agree, performance optimisations like this definitely require significant documentation.

However, for what most of us do, these optimisations should be rare. More emphasis should be placed on code maintainability than performance of individual components in most situations. Hardware is cheap, developer time is expensive.