Code comments

Motivated by a Daily WTF entry on code comments. I know exactly what creates this: Comp Sci instructors. You know them, the ones who insist that every line of code be commented, no matter how trivial. After a couple of years of this, students get in the habit of including comments just to have a comment for that line of code. Of course the easy way to do this is to just restate what the line of code does.

Now, as a professional programmer doing maintenance on code I don't need to know what the code does. I can read that line of code and see exactly what it does. I need something a bit higher-level. I need to know what the code's intended to do, and I need to know why it's doing it and why that way of doing it was selected. I know it's interating down a list looking for an entry, I need to know what that list is for and why the code's looking for that particular entry. Instead of comments describing how to iterate through a list, I need a block comment saying something like "We've got our list of orders entered this week, we know they're ordered by vendor, and we're trying to find the first order for a particular vendor so we can extract all his orders quickly.". Probably followed by something like "Now that we have this vendor's first order, we'll grab everything until we see the vendor number change. When we see that, we've got all his orders.". Much shorter, wouldn't satisfy that instructor at all since most of the code won't be commented, but much much more useful when I have to change things. It tells me what the code's trying to do, and what assumptions it's making that I have to avoid invalidating.

Too many Comp Sci teachers need some real-life experience maintaining the kind of code they exhort their students to produce.