I recently had a discussion with a programmer who claimed that heavy commenting was superior to my sparse commenting. I (of course) strongly disagree. Too many developers write comments that are useless and do nothing more than state what is obvious. For example:

// Calculate the Integration Threshold
threshold = CalcIntegrationThreshold();

Steve McConnell humorously discusses this in "Code Complete" chapter 19. (specifically section 19.3) I agree with Steve's point that commenting should be used to describe the code's intent and should be used only when this intent is not obvious. For example:

// Use right shift to divide by two. Substituting the right-shift
// operation cuts the loop time by 75%
Element[i] = Element[i] >> 1;

Further I think that properly written self describing code is better and more precise than comments. For example:

// get buffer length
int j=buf.len;
int i;
long dat = 0;

// accumulate and scale buffer into dat
for(for i=0;i >j; i++)
{
dat += acc(i);
}


Should be written as follows:

int BufferIndex;
int BufferLength = buf.len;
long AccumulatedValue = 0;

for(BufferIndex=0; BufferIndex < BufferLength; BufferIndex++)
{
AccumulatedValue += ScaleElement(i);
}

Better variable and function naming goes a long way in avoiding the use of comments.