Ugly Comments

This entry over at IT world talks about ugly comments in code and what that means about the code itself. Well, the basic assumption made is that if the comments in the code are ugly, so is the code. This assumption is derived from the principle of attention to detail. This attention to detail required by the programmers who write the code are not exempt from focusing attention to comments.

The problem is that the functional code and the non-functional comments really aren't all that different. I would argue that the comments are as much a part of the running program as the functional code is. They live in the same source files and are one in the same.

Writing great code doesn't really solve the problem of crappy comments either. In fact, the better the code, the more the sub-par comments will stick out. This doesn't mean going into great depths in annotating a piece of functionality. That will often add to the confusion. Go into depth explaining things outside of the source file. Make your comments in the source files concise but complete. Correct spelling doesn't hurt either.