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..”

blog comments powered by Disqus