Exactly this. Comment the why, not the what.
Not sure how that helps or hinders, its just an observation.
It got to the point where the comments were so lengthy and prosaic, you were deterred from reading them just by their very existence.
// --------------------------
for ( int i = 0; i < 50; i++ )
Well, doStuff() only happens while i goes from 0 to 49, so maybe this comment reveals a bug.
It's true that I don't want to see a comment like "loop through this 50 times". But what may not be obvious is the purpose of the loop, the significance of the number 50. Putting in "why" can save hours.
The only exception where I would want a comment that just says what a line of code is for a really complex line, like a complicated regex for example.
Then use an editor/IDE that can automatically hide or fold the comments?
>Dmap source code is very well commented, just look at the amount of green: There is more comments than code !
You know, in my experience that's not a good thing. I work on similar, heavily-commented code and find it extremely painful. At some point it becomes a burden to see the code behind the comments. (And just so no one misinterprets me: I am not against comments /per se/.)
It's like when you read code written by someone who simply loved whitespace and who appended a useless "banner comment" after each real comment[1]:
// If x is less than 3, do stuff 50 times.
// -----------------------------
if ( x < 3 )
{
// While i goes from 0 to 50.
// --------------------------
for ( int i = 0; i < 50; i++ )
{
// Do stuff.
// ---------------
doStuff ( ) ;
}
}
So what would've fitted in one screen of text, if written in a sensible fashion, now requires one and a half screen and lots of scrolling.
[1] The comments in the example are actually both crappy and pointless. Sadly, the program I work on is riddled with them. Please don't write out what the programming language constructs do in English.