I read this post tonight on comments in code. This article pretty much sums up my feelings on commenting code. Here are a couple of highlights:
In general, if a comment already describes what the code does, then the comment is redundant and should be removed. Otherwise, you risk creating a misleading comment, which is worse than no comment at all. As recommended in The Pragmatic Programmer (Addison-Wesley, 2000), strive to keep each piece of knowledge in one piece, as prescribed by the DRY (Don’t Repeat Yourself) principle:
Every piece of knowledge must have a single, unambiguous, and authoritative representation within a system.
Before writing a comment, try to make the code easy to understand so that you need fewer comments. Simple, safe refactorings such as renaming classes, methods, and variables, and extracting well-named methods go a long way toward removing duplication. Then, when all else fails, please leave us a good comment.
