A comment passes on information to the next user (who may be you) and serves some important purposes. A comment also helps you understand the problem and solution by describing it to yourself.
What should be included in comments:
assumptions that were made at particular points in the code
explanations of particularly tricky one-line code
explanations of how processing will proceed for particularly tricky blocks of code.
design philosophies, including pattern names that have been followed
units of measure if not already clear in the variable name. e.g. // this value is in milliseconds
any gotchas that got you, and will probably get others after you
how code has a cascading effect on other code. e.g. // be careful changing these variable names, because they are referenced at runtime by JSPs
why some code was commented out, yet left in place.
constructive ideas how the code could be improved or refactored. Instead of "this should be fixed", “this is rubbish” or "this will never work", try “we might consider refactoring this method because..”
