Code Comments

An interesting debate to have sometimes is about the value of comments in code -- especially comments that are used to auto-generate documentation.I have a strong opinion on this subject. (I have a strong opinion on many subjects, so this isn't altogether surprising.)I think comments by and large are at best useless.Why?I think a good way of looking at this is instead of listing the negatives, let's look at what would make for good comments, then contrast with what happens in the world world.First off, comments need to be accurate, up to date, and informative. Comments in code need to be tested just like the code they are describing. Comments need to be reviewed.The problem is that comments, especially Checkstyle forced comments, is they are useless. You wind up with a comment being nothing more than a restatement of the name of the thing they are describing.

/** The count of widgets. */int widgetCount;

Does that honestly add anything? Not really. At least it's not subtracting, which is the saving grace of it.Then you have comments that are actively lying to the reader. It may have been at some point accurate (to give the benefit of the doubt), but through the passage of time it has aged. Or rather the code aged and the comment stayed the same. Of course the Checkstyle passes just fine since there's a comment there.This gets to the other problem. Unless the comment is tested -- I mean have someone do a black box test of the function based solely on the comment -- I don't have any faith that it's accurate. The comments I wind up seeing are more aspirational than descriptive. It states what the code wanted to implement, maybe copy/pasted from the specs. But when you dive in the code does something else.Comments are a source of evil in general.So, what if the code is confusing? Refactor. Make the functions smaller until you can see what's going on easily. If after trying to refactor it's still confusing, sure you might need a comment.But in all my years of programming, I can count the number of times that's happened on my fingers.Ok, but if you're creating an external published API that needs documentation and all those docs are tested (and ideally written by a tech writer and not the programmer) I'll stand down and agree that you should write the auto-gen comments. But pay someone to test it.