Why, not what

This has been said over and over again, but yet I feel like saying it one more time again.

At the typical beginner class people are taught that comments are good and every line should be commented. So we end up something like this;

for (i = 0; i < np; ++i) // Iterate np times
  tot = tot + s[i];  // Add value to total

Totally useless comments that tell nothing. Contrary to popular opinion this kinds of comments are actually worse than no comments at all, as they tell nothing or even worse, they tell lies.

for (i = 0; i < p; ++i) // Iterate np times
  tot = tot + s[i];  // Add value to total 

p times? np times? What is going on? Someone did some changes, possibly, but never bothered (or remembered) to update comments. If you trust the comments (I generally don't, in cases like this) it is possible that there is a bug in there and now you have to spend time figuring out whether code or comments is right. And then some more time to fix the mess.

So please, don't write comments like that. They're useless.

So what then?

Just few days ago I was going through some code I wrote maybe a year ago and came up with this nugget:

i = 0;
while (inBuffer[i])
  { if (inBuffer[i] != '0')
      { addString(inBuffer);      
        break;
      }
    ++i;
  }
if (!inBuffer[i]) 
  { ...
  }

What is going on here? But right after first confused glance I noticed the comments;

i = 0;
 // if given string has other chars than zeros, use it. 
 // Only zeros (no matter how many) -> ignore
while (inBuffer[i])
  { if (inBuffer[i] != '0')
      { addIdString(inBuffer);      
        break;
      }
    ++i;
  }
if (!inBuffer[i])  // just zeros; discard data
  { ...
  }

Just a few short sentences, but enough - now it immediately made sense. Data passed here is only numbers as ASCIIZ string (no other characters except ending zero, reading the value takes care of that already so validation not needed at this point) and value with just zeroes is to be ignored. So this checks the string, stores it if it isn't just zeros, or throws it away if it is. There absolutely are prettier (as in easier to read without comments) ways to write this but I often prefer efficiency, this is code for relatively tiny MCU anyway.

Granted, it wouldn't have taken me long to figure this out even without comments, but with comments I didn't have to waste time for that. This might not be greatest example there is, but this is a real world example I just stumbled, and of my own making, too.

Neglect is something even this commenting style doesn't fix, however. If I were to change the code and not update the comments to match, next time I visit this code I'd have to spend some time figuring out what is going on - and what should be going on. 

So once again: Code is there to tell reader (be it compiler or human being) what is done. Comments are there to tell reader (human being) why and preferably also how it is done. Together they tell more about the code than either ever could alone. And do keep comments short unless absolutely, positively necessary. Writing novel-length comment is the easiest way to make sure no one will ever read or update it. Keep it short and to the point.