Re: It's "What's the best language" all over again
Perhaps I should clarify what I meant here:
That doesn't mean I never use them but they are used sparingly and typically to provide intent or usage information rather than to actually say what the code is doing.
What I mean is that I dislike seeing this:
// Process all the items in the list.
foreach(var itemToProcess in listOfItemsToProcess) ProcessAnItem(itemToProcess);
or the utterly unforgiveable:
// Increment i
++i;
However the following is acceptable:
// Now that we've got our list of items we need to process them so that when we return the list
// to the caller they are ready to be used.
foreach(var itemToProcess in listOfItemsToProcess) ProcessAnItem(itemToProcess);
In this case that's probably exactly what I'd write however for a more complex code block it would probably be written as:
ProcessItemsToGetThemReadyForUse(listOfItemsToProcess);
I don't hate comments. I only hate comments that tell you things that are obvious from the code - often they are totally unnecessary and the more you describe code the more likely they are to be out of date. But giving an overview of an algorithm or saying whereabouts you are in that algorithm is absolutely fine.