Commenting nowadays is easier than ever. In Java, there are some nice techniques for linking comments to classes, and Java IDEs are good at making comment shells for you. Languages like Clojure even allow you to add a description of a function in the function code itself as an argument.
However we still live in an age where there are often obsolete or poor comments written by good developers – I'm interested in improving the robustness and usefulness of my comments.
In particular I'm interested in Java/Clojure/Python here, but answers don't need be language-specific.
Are there any emerging techniques that validate comments and automatically detect either "flimsy" comments (for example comments with magic numbers, incomplete sentences, etc..) or incorrect comments (for example, detecting mispelled variables or the like).
And more importantly: Are there accepted "commenting-policies" or strategies out there? There is plenty of advice out there on how to code – but what about "how to comment?"
Best Answer
Names/documentation should tell you what you are doing.
Implementation should tell you how you are doing it.
Comments should tell you why you do it the way you do.