I’ve always said “WHY” is the most important thing to comment, and always gotten static over it. I usually include a file, or big comment block somewhere where it makes sense, that just states the purpose and general design philosophy of an application, and any important assumptions in force.
All that aside, I’ve actually noticed a trend in a lot of developers to actively NOT READ COMMENTS. Whether because they are used to comments being bad, inaccurate, out of date, nonexistent, or maybe they just don’t like to read seems to vary, but on many occasions Ive been asked to assist someone figure out some old code or another, and figured out their problem just by reading the comments and groking the intent of the code rather than trying to read every last line of it.
Another related trend I’ve noticed is a tendency to rely too much on debugging to figure out what code does rather than interpreting it mentally while reading thru it. I’ve watched too many developers go line by line in a debugger when simply looking at the code, a call chain, some names, and a comment or two is usually sufficient to pinpoint an area that is likely to have problems.
And finally, my big pet peeve is when developers make code changes to legacy / older code and make no comment that they are making a change or WHEN or WHY they are making a change. Source Control is great and all that, but I’d rather not have to review all possible versions of a file directly to ascertain when a change was introduced and for what reason if I have to reconstruct how something bad was permitted to happen in PROD, how long it was possible for it to occur, and what else was affected.
Often the most useful comments are the ones that have little to do with the code itself and more to do with flagging bug fixes and functionality changes with a date and a justification (even if its just a reference to a bug tracker system or ticket).