Perhaps, in my (not so) youthful exuberance, I was a little too dogmatic and down on code commenting in my previous post on the subject.
Coincidentally, on the ALT.NET mailing list, a discussion started up about commenting code and the same type of sentiments and reactions were heard.
Greg Young made a great point by posting an example of a great comment:
/*
You will notice that this code is using a linked list and doing an online insertion sort.
You may think that its a good refactor to use say a sorted list, its not. The
insertion sort is being used even though it is O(n) here because we found that
90% of our data is within the first 3 entries anyways and this is the
worst case for array based structures as you must copy the entirety of the
array which is usually worse than the actual iteration. A refactor to a skip
list may prove beneficial in some circumstances but with an average
case of O(3) we figured it was needless complexity being brought in.
*/
Now, I'll have to admit, this is a great comment and I would have no hesitation leaving it in the code (assuming it still had anything to do with the code beneath).
Do *YOU* have a great example of commenting at its best? Please prove my original sentiments wrong. Show me the GOOD code comments!
(NOTE: Feel free to post it on your blog, if you have one, and drop a link here as it may be easier to read than in the little comment box thingee)